Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)
Did this page help you?  Yes | No |  Tell us about it...
« 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.

Configuring a Web Page Redirect

If your Amazon S3 bucket is configured for website hosting, you can redirect requests for an object to another object in the same bucket or to an external URL. You set the redirect by adding the x-amz-website-redirect-location property to the object metadata. The website then interprets the object as 301 redirect. To redirect a request to another object, you set the redirect location to the key of the target object. To redirect a request to an external URL, you set the redirect location to the URL that you want. For more information about object metadata, see System-Defined Metadata.

A bucket configured for website hosting has both the website endpoint and the REST endpoint. A request for a page that is configured as a 301 redirect has the following possible outcomes, depending on the endpoint of the request:

  • Region-specific website endpoint – Amazon S3 redirects the page request according to the value of the x-amz-website-redirect-location property.

  • REST endpoint – Amazon S3 does not redirect the page request. It returns the requested object.

For more information about the endpoints, see Key Differences Between the Amazon Website and the REST API Endpoint.

You can set a page redirect from the Amazon S3 console or by using the Amazon S3 REST API

Page Redirect Support in the Amazon S3 Console

You can use the Amazon S3 console to set the website redirect location in the metadata of the object. When you set a page redirect, you can either keep or delete the source object content. For example, suppose you have a page1.html object in your bucket. To redirect any requests for this page to another object, page2.html, you can do one of the following:

  • To keep the content of the page1.html object and only redirect page requests, under Properties for page1.html, click the Metadata tab. Add Website Redirect Location to the metadata, as shown in the following example, and set its value to /page2.html. The / prefix in the value is required.

    You can also set the value to an external URL, such as http://www.example.com.

  • To delete the content of the page1.html object and redirect requests, you can upload a new zero-byte object with the same key, page1.html, to replace the existing object, and then specify Website Redirect Location for page1.html in the upload process. For information about uploading an object, go to Uploading Objects into Amazon S3 in the Amazon Simple Storage Service Console User Guide.

Setting a Page Redirect from the REST API

The following Amazon S3 API actions support the x-amz-website-redirect-location header in the request. Amazon S3 stores the header value in the object metadata as x-amz-website-redirect-location.

When setting a page redirect you can either keep or delete the object content. For example, suppose you have a page1.html object in your bucket.

  • To keep the content of page1.html and only redirect page requests, you can submit a PUT Object - Copy request to create a new page1.html object that uses the existing page1.html object as the source. In your request, you set the x-amz-website-redirect-location header. When the request is complete, you have the original page with its content unchanged, but Amazon S3 redirects any requests for the page to the redirect location that you specify.

  • To delete the content of the page1.html object and redirect requests for the page, you can send a PUT Object request to upload a zero-byte object that has the same object key, page1.html. In the PUT request, you set x-amz-website-redirect-location for page1.html to the new object. When the request is complete, page1.html has no content, and any requests will be redirected to the location that is specified by x-amz-website-redirect-location.

When you retrieve the object using the GET Object action, along with other object metadata, Amazon S3 returns the x-amz-website-redirect-location header in the response.