# 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](https://docs.aws.amazon.com/general/latest/gr/s3.html) 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 points** ‐`s3-accesspoint.Region.amazonaws.com`
+ **Dual-stack** ‐ `s3.dualstack.Region.amazonaws.com`
For a complete list of Amazon S3 Regions and endpoints, see [Amazon S3 endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html) in the *Amazon Web Services 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 [Path-style requests ](https://docs.aws.amazon.com//AmazonS3/latest/userguide/VirtualHosting.html#path-style-access).
**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 [Path-style requests ](https://docs.aws.amazon.com//AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access).
```
1. DELETE /puppy.jpg HTTP/1.1
2. Host: examplebucket.s3.us-west-2.amazonaws.com
3. Date: Mon, 11 Apr 2016 12:00:00 GMT
4. x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT
5. Authorization: authorization string
```
**Example Path-style request**
Following is an example of a path-style version of the same request.
```
1. DELETE /examplebucket/puppy.jpg HTTP/1.1
2. Host: s3.us-west-2.amazonaws.com
3. Date: Mon, 11 Apr 2016 12:00:00 GMT
4. x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT
5. Authorization: authorization string
```
You will receive an HTTP response code 307 Temporary Redirect error and a message indicating what the correct URI is for your resource if you try to access a bucket outside the US East (N. Virginia) region with path-style syntax that uses either of the following:
For more information about path-style requests, see [Path-style requests ](https://docs.aws.amazon.com//AmazonS3/latest/userguide/VirtualHosting.html#path-style-access).
Update (September 23, 2020) – To make sure that customers have the time that they need to transition to virtual-hosted–style URLs, we have decided to delay the deprecation of path-style URLs. For more information, see [Amazon S3 Path Deprecation Plan – The Rest of the Story](https://aws.amazon.com/blogs/aws/amazon-s3-path-deprecation-plan-the-rest-of-the-story/) in the *AWS News Blog*.
## 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.
```
1. GET /puppy.jpg HTTP/1.1
2. Host: examplebucket.s3.dualstack.us-west-2.amazonaws.com
3. Date: Mon, 11 Apr 2016 12:00:00 GMT
4. x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT
5. 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.
```
1. GET /examplebucket/puppy.jpg HTTP/1.1
2. Host: s3.dualstack.us-west-2.amazonaws.com
3. Date: Mon, 11 Apr 2016 12:00:00 GMT
4. x-amz-date: Mon, 11 Apr 2016 12:00:00 GMT
5. Authorization: authorization string
```
For more information about dual-stack endpoints, see [Using Amazon S3 dual-stack endpoints](dual-stack-endpoints.md).
For more information about making requests using the REST API, see the topics below.
**Topics**
+ [
## Constructing S3 hostnames for REST API requests
](#constructing-hostname-rest-api-requests)
+ [
## Virtual hosted‐style and path‐style requests
](#virtual-hosted-path-style-requests)
+ [
## Making requests to dual-stack endpoints by using the REST API
](#rest-api-dual-stack)
+ [
# Request redirection and the REST API
](RESTRedirect.md)
+ [
# Request routing
](UsingRouting.md)
# Request redirection and the REST API
**Topics**
+ [
## Redirects and HTTP user-agents
](#RESTRedirectHTTPUserAgents)
+ [
## Redirects and 100-Continue
](#RESTRedirect100Continue)
+ [
## Redirect example
](#RESTRedirectExample)
This section describes how to handle HTTP redirects by using the Amazon S3 REST API. For general information about Amazon S3 redirects, see [Making requests](MakingRequests.md) in the Amazon Simple Storage Service API Reference.
## Redirects and HTTP user-agents
Programs that use the Amazon S3 REST API should handle redirects either at the application layer or the HTTP layer. Many HTTP client libraries and user agents can be configured to correctly handle redirects automatically; however, many others have incorrect or incomplete redirect implementations.
Before you rely on a library to fulfill the redirect requirement, test the following cases:
+ Verify all HTTP request headers are correctly included in the redirected request (the second request after receiving a redirect) including HTTP standards such as Authorization and Date.
+ Verify non-GET redirects, such as PUT and DELETE, work correctly.
+ Verify large PUT requests follow redirects correctly.
+ Verify PUT requests follow redirects correctly if the 100-continue response takes a long time to arrive.
HTTP user-agents that strictly conform to RFC 2616 might require explicit confirmation before following a redirect when the HTTP request method is not GET or HEAD. It is generally safe to follow redirects generated by Amazon S3 automatically, as the system will issue redirects only to hosts within the amazonaws.com domain and the effect of the redirected request will be the same as that of the original request.
## Redirects and 100-Continue
To simplify redirect handling, improve efficiencies, and avoid the costs associated with sending a redirected request body twice, configure your application to use 100-continues for PUT operations. When your application uses 100-continue, it does not send the request body until it receives an acknowledgement. If the message is rejected based on the headers, the body of the message is not sent. For more information about 100-continue, go to [RFC 2616 Section 8.2.3](http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.2.3)
**Note**
According to RFC 2616, when using `Expect: Continue` with an unknown HTTP server, you should not wait an indefinite period before sending the request body. This is because some HTTP servers do not recognize 100-continue. However, Amazon S3 does recognize if your request contains an `Expect: Continue` and will respond with a provisional 100-continue status or a final status code. Additionally, no redirect error will occur after receiving the provisional 100 continue go-ahead. This will help you avoid receiving a redirect response while you are still writing the request body.
## Redirect example
This section provides an example of client-server interaction using HTTP redirects and 100-continue.
Following is a sample PUT to the `quotes.s3.amazonaws.com` bucket.
```
1. PUT /nelson.txt HTTP/1.1
2. Host: quotes.s3.amazonaws.com
3. Date: Mon, 15 Oct 2007 22:18:46 +0000
4.
5. Content-Length: 6
6. Expect: 100-continue
```
Amazon S3 returns the following:
```
1. HTTP/1.1 307 Temporary Redirect
2. Location: http://quotes.s3-4c25d83b.amazonaws.com/nelson.txt?rk=8d47490b
3. Content-Type: application/xml
4. Transfer-Encoding: chunked
5. Date: Mon, 15 Oct 2007 22:18:46 GMT
6.
7. Server: AmazonS3
8.
9.
10.
11. TemporaryRedirect
12. Please re-send this request to the
13. specified temporary endpoint. Continue to use the
14. original request endpoint for future requests.
15.
16. quotes.s3-4c25d83b.amazonaws.com
17. quotes
18.
```
The client follows the redirect response and issues a new request to the `quotes.s3-4c25d83b.amazonaws.com` temporary endpoint.
```
1. PUT /nelson.txt?rk=8d47490b HTTP/1.1
2. Host: quotes.s3-4c25d83b.amazonaws.com
3. Date: Mon, 15 Oct 2007 22:18:46 +0000
4.
5. Content-Length: 6
6. Expect: 100-continue
```
Amazon S3 returns a 100-continue indicating the client should proceed with sending the request body.
```
1. HTTP/1.1 100 Continue
```
The client sends the request body.
```
1. ha ha\n
```
Amazon S3 returns the final response.
```
1. HTTP/1.1 200 OK
2. Date: Mon, 15 Oct 2007 22:18:48 GMT
3.
4. ETag: "a2c8d6b872054293afd41061e93bc289"
5. Content-Length: 0
6. Server: AmazonS3
```
# Request routing
Programs that make requests against buckets created using the [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) API that include a [CreateBucketConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucketConfiguration.html) must support redirects. Additionally, some clients that do not respect DNS TTLs might encounter issues.
This section describes routing and DNS issues to consider when designing your service or application for use with Amazon S3.
## Request redirection and the REST API
Amazon S3 uses the Domain Name System (DNS) to route requests to facilities that can process them. This system works effectively, but temporary routing errors can occur. If a request arrives at the wrong Amazon S3 location, Amazon S3 responds with a temporary redirect that tells the requester to resend the request to a new endpoint. If a request is incorrectly formed, Amazon S3 uses permanent redirects to provide direction on how to perform the request correctly.
**Important**
To use this feature, you must have an application that can handle Amazon S3 redirect responses. The only exception is for applications that work exclusively with buckets that were created without ``. For more information about location constraints, see [Accessing and listing an Amazon S3 bucket ](https://docs.aws.amazon.com//AmazonS3/latest/userguide/access-bucket-intro.html).
For all Regions that launched after March 20, 2019, if a request arrives at the wrong Amazon S3 location, Amazon S3 returns an HTTP 400 Bad Request error.
For more information about enabling or disabling an AWS Region, see [AWS Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the *AWS General Reference*.
**Topics**
+ [
### DNS routing
](#DNSRouting)
+ [
### Temporary request redirection
](#TemporaryRedirection)
+ [
### Permanent request redirection
](#RedirectsPermanentRedirection)
+ [
### Request redirection examples
](#redirect-examples)
### DNS routing
DNS routing routes requests to appropriate Amazon S3 facilities. The following figure and procedure show an example of DNS routing.
![\[Diagram showing steps that occur when a DNS server routes requests from the client to facility B.\]](http://docs.aws.amazon.com/AmazonS3/latest/API/images/DNS_virthost.png)
**DNS routing request steps**
1. The client makes a DNS request to get an object stored on Amazon S3.
1. The client receives one or more IP addresses for facilities that can process the request. In this example, the IP address is for Facility B.
1. The client makes a request to Amazon S3 Facility B.
1. Facility B returns a copy of the object to the client.
### Temporary request redirection
A temporary redirect is a type of error response that signals to the requester that they should resend the request to a different endpoint. Due to the distributed nature of Amazon S3, requests can be temporarily routed to the wrong facility. This is most likely to occur immediately after buckets are created or deleted.
For example, if you create a new bucket and immediately make a request to the bucket, you might receive a temporary redirect, depending on the location constraint of the bucket. If you created the bucket in the US East (N. Virginia) AWS Region, you will not see the redirect because this is also the default Amazon S3 endpoint.
However, if the bucket is created in any other Region, any requests for the bucket go to the default endpoint while the bucket's DNS entry is propagated. The default endpoint redirects the request to the correct endpoint with an HTTP 302 response. Temporary redirects contain a URI to the correct facility, which you can use to immediately resend the request.
**Important**
Don't reuse an endpoint provided by a previous redirect response. It might appear to work (even for long periods of time), but it might provide unpredictable results and will eventually fail without notice.
The following figure and procedure shows an example of a temporary redirect.
![\[Diagram showing steps that occur when a client sends a request to B and is redirected to C.\]](http://docs.aws.amazon.com/AmazonS3/latest/API/images/DNS_virthost_redirect.png)
**Temporary request redirection steps**
1. The client makes a DNS request to get an object stored on Amazon S3.
1. The client receives one or more IP addresses for facilities that can process the request.
1. The client makes a request to Amazon S3 Facility B.
1. Facility B returns a redirect indicating the object is available from Location C.
1. The client resends the request to Facility C.
1. Facility C returns a copy of the object.
### Permanent request redirection
A permanent redirect indicates that your request addressed a resource inappropriately. For example, permanent redirects occur if you use a path-style request to access a bucket that was created using ``. For more information, see [Accessing and listing an Amazon S3 bucket ](https://docs.aws.amazon.com//AmazonS3/latest/userguide/access-bucket-intro.html).
To help you find these errors during development, this type of redirect does not contain a Location HTTP header that allows you to automatically follow the request to the correct location. Consult the resulting XML error document for help using the correct Amazon S3 endpoint.
### Request redirection examples
The following are examples of temporary request redirection responses.
#### REST API temporary redirect response
```
1. HTTP/1.1 307 Temporary Redirect
2. Location: http://awsexamplebucket1.s3-gztb4pa9sq.amazonaws.com/photos/puppy.jpg?rk=e2c69a31
3. Content-Type: application/xml
4. Transfer-Encoding: chunked
5. Date: Fri, 12 Oct 2007 01:12:56 GMT
6. Server: AmazonS3
7.
8.
9.
10. TemporaryRedirect
11. Please re-send this request to the specified temporary endpoint.
12. Continue to use the original request endpoint for future requests.
13. awsexamplebucket1.s3-gztb4pa9sq.amazonaws.com
14.
```
#### SOAP API temporary redirect response
**Note**
SOAP APIs for Amazon S3 are not available for new customers, and are approaching End of Life (EOL) on October 31, 2025. We recommend that you use either the REST API or the AWS SDKs.
```
1.
2.
3. soapenv:Client.TemporaryRedirect
4. Please re-send this request to the specified temporary endpoint.
5. Continue to use the original request endpoint for future requests.
6.
7. images
8. s3-gztb4pa9sq.amazonaws.com
9.
10.
11.
```
## DNS considerations
One of the design requirements of Amazon S3 is extremely high availability. One of the ways we meet this requirement is by updating the IP addresses associated with the Amazon S3 endpoint in DNS as needed. These changes are automatically reflected in short-lived clients, but not in some long-lived clients. Long-lived clients will need to take special action to re-resolve the Amazon S3 endpoint periodically to benefit from these changes. For more information about virtual machines (VMs), refer to the following:
+ For Java, Sun's JVM caches DNS lookups forever by default; go to the "InetAddress Caching" section of [the InetAddress documentation](https://docs.oracle.com/javase/9/docs/api/java/net/InetAddress.html) for information on how to change this behavior.
+ For PHP, the persistent PHP VM that runs in the most popular deployment configurations caches DNS lookups until the VM is restarted. Go to [the getHostByName PHP docs.](http://us2.php.net/manual/en/function.gethostbyname.php)