Revision 1107977 of Redirections in HTTP

<p>{{HTTPSidebar}}</p>

<p class="summary">URL Redirection, or URL forwarding, is a technique to keep links alive while the actual resource, being a page, a form or a whole Web apps, is located at another URL. HTTP provides a special kind of responses, <em><strong>HTTP Redirects</strong></em>, to perform this operation used for numerous goals: temporary redirection while site maintenance is happening, permanent redirection to keep external links working after a change in the architecture, progress pages when uploading a file, …</p>

<h2 id="Principle">Principle</h2>

<p>In HTTP, a redirection is triggered by the server by sending special responses to a request: <em>redirects</em>. HTTP redirects are responses with a status code of <code>3xx</code>. A browser, when receiving a redirect response, use the new URL provided and immediately loads it: most of the time, the redirection is transparent for the user, beside a small performance hit.</p>

<p>(image)</p>

<p>They are several types of redirects and they fell in three categories: permanent, temporary and special redirections.</p>

<h3 id="Permanent_redirections">Permanent redirections</h3>

<p>These redirections are meant to last forever. They imply that the original URL is no more to be used and that the new one has to preferred. Browsers just don't follow such links, but search engine robots trigger an update of the URL associated to the resource in their index.</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Code</th>
   <th scope="col">Text</th>
   <th scope="col">Method handling</th>
   <th scope="col">Typical use case</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>301</code></td>
   <td><code>Moved Permanently</code></td>
   <td>{{HTTPMethod("GET")}} methods unchanged.<br />
    Others may or may not be changed to {{HTTPMethod("GET")}}.<sup><a href="#attr1">[1]</a></sup></td>
   <td>Reorganization of a Web site.</td>
  </tr>
  <tr>
   <td><code>308</code></td>
   <td><code>Permanent Redirect</code></td>
   <td>Method and body not changed.</td>
   <td>Reorganization of a Web site, with non-GET links/operations.</td>
  </tr>
 </tbody>
</table>

<p><a id="attr1" name="attr1"></a>[1] The specification didn't intended to allow method changing this, but practically there are user agents out there doing this. <code>308</code> has been created to remove the ambiguity of the behavior when using non-<code>GET</code> methods.</p>

<h3 id="Temporary_redirections">Temporary redirections</h3>

<p>Sometimes the requested resource cannot be accessed from its canonical location, but it can be accessed from another place. In this case a temporary redirect can be used: browsers just follow such links, but search engine robots don't memorize the new link. Temporary redirections are also used when creating, updating and deleting resources to present temporary progress pages.</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Code</th>
   <th scope="col">Text</th>
   <th scope="col">Method handling</th>
   <th scope="col">Typical use case</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>302</code></td>
   <td><code>Found</code></td>
   <td>{{HTTPMethod("GET")}} methods unchanged.<br />
    Others may or may not be changed to {{HTTPMethod("GET")}}.<sup><a href="#attr2">[2]</a></sup></td>
   <td>The Web page is temporary not available for reasons that have not been unforeseen. That way, search engines doesn't update their links.</td>
  </tr>
  <tr>
   <td><code>303</code></td>
   <td><code>See Other</code></td>
   <td>{{HTTPMethod("GET")}} methods unchanged.<br />
    Others <em>changed</em> to <code>GET</code> (body lost).</td>
   <td>Used to redirect after a {{HTTPMethod("PUT")}} or a {{HTTPMethod("POST")}} to prevent a refresh of the page that would re-trigger the operation.</td>
  </tr>
  <tr>
   <td><code>307</code></td>
   <td><code>Temporary Redirect</code></td>
   <td>Method and body not changed</td>
   <td>The Web page is temporary not available for reasons that have not been unforeseen. That way, search engines doesn't update their links. Better than <code>302</code> when non-GET links/operations are on available on the site.</td>
  </tr>
 </tbody>
</table>

<p><a id="attr2" name="attr2"></a>[2] The specification didn't intended to allow method changing this, but practically there are user agents out there doing this. <code>307</code> has been created to remove the ambiguity of the behavior when using non-<code>GET</code> methods.</p>

<h3 id="Special_redirections">Special redirections</h3>

<p>In addition to these usual redirections, there are two specific redirections. The {{HTTPStatus("304")}} <code>Not Modified</code> redirects that in fact redirects a page to the locally cached copy (that was stale), and {{HTTPStatus("300")}} <code>Multiple Choice</code> that is a kind of manual redirection: the body, presented by the browser as a Web page, lists the possible redirections and the user click on one to select it.</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Code</th>
   <th scope="col">Text</th>
   <th scope="col">Typical use case</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><code>300</code></td>
   <td><code>Multiple Choice</code></td>
   <td>Not many: the choices are listed in an html page in the body. Could be serverd with a {{HTTPStatus("200")}} <code>OK</code> status.</td>
  </tr>
  <tr>
   <td><code>304</code></td>
   <td><code>Not Modified</code></td>
   <td>Cache refresh: this indicates that the cache value is still fresh an can be used.</td>
  </tr>
 </tbody>
</table>

<h2 id="Alternative_way_of_specifying_redirections">Alternative way of specifying redirections</h2>

<p>HTTP redirects aren't the only way to defining redirections. There are two other methods: HTML redirections using the {{HTMLElement("meta")}} element, and JavaScript redirections using the <a href="/en-US/docs/Web/API/Document_Object_Model">DOM</a>.</p>

<h3 id="HTML_redirections">HTML redirections</h3>

<p>HTTP redirects are the preferred way to create redirections, but sometimes the Web developer doesn't have the control over the server and cannot configure it. For these specific cases, the Web devs can craft an HTML page with a {{HTMLElement("meta")}} element with the {{htmlattrxref("http-equiv", "meta")}} attribute set to <code>refresh</code> in the {{HTMLElement("head")}} of the page. When displaying the page, the browser will find this element and will go to the indicating page.</p>

<pre class="brush: html">
&lt;head&gt; 
  &lt;meta http-equiv="refresh" content="0;URL='https://www.example.com/'" /&gt;
&lt;/head&gt;
</pre>

<p>The {{htmlattrxref("content")}} starts with a number indicating how many seconds the browser should wait before redirecting to the given URL. Always set it to <code>0</code>, to help for accessibility.</p>

<p>Obviously, this method work only with HTML pages (or similar) and cannot be used for images or other type of content.</p>

<p>Note that these redirections break the back button in browser: you can go back to a page with this header and it instantaneously moves forward again. Users dont' like such behavior.</p>

<h3 id="JavaScript_redirections">JavaScript redirections</h3>

<p>Redirections in JavaScript are pretty easy: just give a new value to {{domxref("window.location")}} and the new page is loaded.</p>

<pre class="brush: js">
window.location = "https://www.example.com/";</pre>

<p>Like HTML redirections, this can't work on any resources, and obviously this will work only on clients that execute JavaScript. On this other side, there is more freedom as you can trigger the redirection only if some conditions are met.</p>

<h3 id="Order_of_precedence">Order of precedence</h3>

<p>With three ways of doing URL redirections comes the natural questions: when several methods are specifies, which one is applied? The order of precedence is the following:</p>

<ol>
 <li>HTTP Redirects are always executed first, there is not even a page transmitted, and of course not even read.</li>
 <li>HTML Redirects ({{HTMLElement("meta")}}) are executed if there wasn't any HTTP redirects.</li>
 <li>JavaScript Redirects are used as the last resort, and only if the JavaScript is enabled on the client side.</li>
</ol>

<p>When possible, always try to use HTTP redirects, and don't put a {{HTMLElement("meta")}} just in case in relevant pages, it will only confuses developers wanting to fix a problem the day the HTTP redirects and the HTML ones are no more identical.</p>

<h2 id="Use_cases">Use cases</h2>

<p>There are numerous usages for redirects, but as they come as a performance cost, there use should be minimized.</p>

<h3>Domain aliasing</h3>

<p>Ideally there is one location, and therefore one URL, for one resource. But there are plenty of good reasons for wanted to have alternatives names for a resource (several domains, like with and without the www. prefix, shorter easy to remember URLs, …). In this cases, rather than duplicate the resource, it is useful to use a redirect to the one true URL.</p>

<p>For example: Your site resides under the <code>www.example.com</code> domain. But you want people accessing your pages to <code>example.com</code> to be able to reach them too. You set redirections between each <code>example.com</code> page to <code>www.example.com.</code></p>

<h3>Keeping links alive</h3>

<p>When you restructure a Web sites, URL of resources change. Even if you can update the internal links of your Web site to match the new naming scheme, you have no control over the URLs used by external resources. You don't want to break this link as they bring you valuable users (and help your SEO), so you set up redirects from the old URLs to the new ones.</p>

<div class="note">
<p>Even if this technique also works for internal links, you should try to avoid having internal redirects. A redirect has a significant performance cost (as an extra HTTP request is done) and if you can avoid it by correcting internal links, you should just do it.</p>
</div>

<h3>Temporary responses to <code>POST</code> or <code>PUT</code> requests</h3>

<p>When posting</p>

<h2 id="Configuring_redirects_in_common_servers">Configuring redirects in common servers</h2>

<h2 id="Avoiding_redirection_loops">Avoiding redirection loops</h2>