Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Working with Amazon S3 Buckets

Every object stored in Amazon S3 is contained in a bucket. Buckets partition the namespace of objects stored in Amazon S3 at the top level. Within a bucket, you can use any names for your objects, but bucket names must be unique across all of Amazon S3.

Buckets are similar to Internet domain names. Just as Amazon is the only owner of the domain name aws.amazon.com, only one person or organization can own a bucket within Amazon S3. After you create a uniquely named bucket in Amazon S3, you can organize and name the objects within the bucket in any way you like, and the bucket will remain yours for as long as you want and as long as you have the Amazon S3 account.

The similarities between buckets and domain names is not a coincidence—there is a direct mapping between Amazon S3 buckets and subdomains of s3.amazonaws.com. Objects stored in Amazon S3 are addressable by the REST API under the domain bucketname.s3.amazonaws.com. For example, if the object homepage.html is stored in the Amazon S3 bucket mybucket, its address would be http://mybucket.s3.amazonaws.com/homepage.html. For more information, see Virtual Hosting of Buckets.

To use the REST API to determine whether a bucket name exists, use an HTTP HEAD request, specify the name of the bucket, and set max-keys to 0. A NoSuchBucket response indicates that the bucket is not available, an AccessDenied response indicates that someone else owns the bucket, and a Success response indicates that you own the bucket or have permission to access it. To use SOAP to determine whether a bucket name exists, use ListBucket, and set MaxKeys to 0.

Note

SOAP support over HTTP is deprecated, but it is still available over HTTPS. New Amazon S3 features will not be supported for SOAP. We recommend that you use either the REST API or the AWS SDKs.

For a list of AWS regions where you can create a bucket, go to Regions and Endpoints in the AWS General Reference.

Bucket Configuration Errors

The following list shows the errors Amazon S3 can return in response to bucket configuration requests.