Making requests using the REST API - Amazon Simple Storage Service

Making requests using the REST API

This section contains information on how to make requests to Amazon S3 endpoints by using the REST API. For a list of Amazon S3 endpoints, see Regions and Endpoints in the AWS General Reference.

Constructing S3 hostnames for REST API requests

Amazon S3 endpoints follow the structure shown below:

s3.Region.amazonaws.com

Amazon S3 Access Points endpoints and dual-stack endpoints also follow the standard structure:

  • Amazon S3 Access Pointss3-accesspoint.Region.amazonaws.com

  • Dual-stacks3.dualstack.Region.amazonaws.com

For a complete list of Amazon S3 Regions and endpoints, see Amazon S3 Regions and Endpoints in the AWS General Reference.

Virtual hosted‐style and path‐style requests

When making requests by using the REST API, you can use virtual hosted–style or path-style URIs for the Amazon S3 endpoints. For more information, see Virtual hosting of buckets.

Example Virtual hosted–Style request

Following is an example of a virtual hosted–style request to delete the puppy.jpg file from the bucket named examplebucket in the US West (Oregon) Region. For more information about virtual hosted-style requests, see Virtual Hosted-Style Requests.

DELETE /puppy.jpg HTTP/1.1 Host: examplebucket.s3.us-west-2.amazonaws.com Date: Mon, 11 Apr 2016 12:00:00 GMT x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT Authorization: authorization string

Example Path-style request

Following is an example of a path-style version of the same request.

DELETE /examplebucket/puppy.jpg HTTP/1.1 Host: s3.us-west-2.amazonaws.com Date: Mon, 11 Apr 2016 12:00:00 GMT x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT Authorization: authorization string

Currently Amazon S3 supports virtual hosted-style and path-style access in all Regions, but this will be changing (see the following Important note.

For more information about path-style requests, see Path-Style Requests.

Important

Buckets created after September 30, 2020, will support only virtual hosted-style requests. Path-style requests will continue to be supported for buckets created on or before this date. For more information, see Amazon S3 Path Deprecation Plan – The Rest of the Story.

Making requests to dual-stack endpoints by using the REST API

When using the REST API, you can directly access a dual-stack endpoint by using a virtual hosted–style or a path style endpoint name (URI). All Amazon S3 dual-stack endpoint names include the region in the name. Unlike the standard IPv4-only endpoints, both virtual hosted–style and a path-style endpoints use region-specific endpoint names.

Example Virtual hosted–Style dual-stack endpoint request

You can use a virtual hosted–style endpoint in your REST request as shown in the following example that retrieves the puppy.jpg object from the bucket named examplebucket in the US West (Oregon) Region.

GET /puppy.jpg HTTP/1.1 Host: examplebucket.s3.dualstack.us-west-2.amazonaws.com Date: Mon, 11 Apr 2016 12:00:00 GMT x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT Authorization: authorization string

Example Path-style dual-stack endpoint request

Or you can use a path-style endpoint in your request as shown in the following example.

GET /examplebucket/puppy.jpg HTTP/1.1 Host: s3.dualstack.us-west-2.amazonaws.com Date: Mon, 11 Apr 2016 12:00:00 GMT x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT Authorization: authorization string

For more information about dual-stack endpoints, see Using Amazon S3 dual-stack endpoints.