source: specs/rfc7538.xml @ 2737

Last change on this file since 2737 was 2737, checked in by julian.reschke@…, 5 years ago

update specs

  • Property svn:executable set to *
File size: 15.2 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
3<?rfc toc="yes"?>
4<?rfc symrefs="yes"?>
5<?rfc sortrefs="yes"?>
6<?rfc compact="yes"?>
7<?rfc comments="yes"?>
8<?rfc inline="yes"?>
9<?rfc subcompact="no"?>
10<?rfc rfcedstyle="yes"?>
11<?rfc-ext allow-markup-in-artwork="yes" ?>
12
13<!DOCTYPE rfc [
14  <!ENTITY mdash "&#8212;">
15  <!ENTITY Note "<x:h xmlns:x='http://purl.org/net/xml2rfc/ext'>Note:</x:h>">
16  <!ENTITY MAY "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MAY</bcp14>">
17  <!ENTITY MUST "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MUST</bcp14>">
18  <!ENTITY MUST-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>MUST NOT</bcp14>">
19  <!ENTITY OPTIONAL "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>OPTIONAL</bcp14>">
20  <!ENTITY RECOMMENDED "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>RECOMMENDED</bcp14>">
21  <!ENTITY REQUIRED "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>REQUIRED</bcp14>">
22  <!ENTITY SHALL "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHALL</bcp14>">
23  <!ENTITY SHALL-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHALL NOT</bcp14>">
24  <!ENTITY SHOULD "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHOULD</bcp14>">
25  <!ENTITY SHOULD-NOT "<bcp14 xmlns='http://purl.org/net/xml2rfc/ext'>SHOULD NOT</bcp14>">
26]>
27<rfc xmlns:x="http://purl.org/net/xml2rfc/ext" obsoletes="7238" xmlns:ed="http://greenbytes.de/2002/rfcedit" ipr="trust200902" number="7538" category="std" xml:lang="en">
28
29  <x:feedback template="mailto:ietf-http-wg@w3.org?subject={docname},%20%22{section}%22&amp;body=&lt;{ref}&gt;:"/>
30
31        <front>
32  <title abbrev="HTTP Status Code 308">The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)</title>
33  <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke">
34    <organization abbrev="greenbytes">greenbytes GmbH</organization>
35    <address>
36      <postal>
37        <street>Hafenweg 16</street>
38        <city>Muenster</city><region>NW</region><code>48155</code>
39        <country>Germany</country>
40      </postal>
41      <email>julian.reschke@greenbytes.de</email>       
42      <uri>http://greenbytes.de/tech/webdav/</uri>     
43    </address>
44  </author>
45
46  <date year="2015" month="April"/>
47 
48  <area>Applications</area>
49  <workgroup>HTTP</workgroup>
50  <keyword>HTTP</keyword>
51  <keyword>redirect</keyword>
52  <keyword>status code</keyword>
53
54  <abstract>
55    <t>
56      This document specifies the additional Hypertext Transfer Protocol (HTTP)
57      status code 308 (Permanent Redirect).
58    </t>
59  </abstract>
60  </front>
61
62  <middle>
63<section title="Introduction" anchor="introduction">
64<t>
65  HTTP defines a set of status codes for the purpose of redirecting a request
66  to a different URI (<xref target="RFC3986"/>). The history of these status codes is summarized in
67  <xref target="RFC7231" x:rel="#status.3xx"/>, which
68  also classifies the existing status codes into four categories.
69</t>
70<t>
71  The first of these categories contains the status codes 301 (Moved Permanently),
72  302 (Found), and 307 (Temporary Redirect), which can be classified as below:
73</t>
74<texttable align="left" suppress-title="true">
75<ttcol/>
76<ttcol>Permanent</ttcol>
77<ttcol>Temporary</ttcol>
78<c>Allows changing the request method from POST to GET</c>
79<c>301</c>
80<c>302</c>
81<c>Does not allow changing the request method from POST to GET</c>
82<c>-</c>
83<c>307</c>
84</texttable>
85<t>
86  <xref target="RFC7231" x:rel="#status.307"/>
87  states that it does not define a permanent variant of status code 307;
88  this specification adds
89  the status code 308, defining this missing variant (<xref target="status.308"/>).
90</t>
91<t>
92  This specification contains no technical changes from the Experimental RFC 7238,
93  which it obsoletes.
94</t>
95</section> 
96
97<section title="Notational Conventions" anchor="notational.conventions">
98<t>
99   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
100   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
101   document are to be interpreted as described in <xref target="RFC2119"/>.
102</t>
103</section>
104
105<section title="308 Permanent Redirect" anchor="status.308">
106
107
108<t>
109   The <x:dfn>308 (Permanent Redirect)</x:dfn> status code indicates that the
110   target resource has been assigned a new permanent URI and
111   any future references to this resource ought to use one of the enclosed
112   URIs. Clients with link editing capabilities ought to automatically re-link
113   references to the effective request URI (<xref target="RFC7230" x:rel="#effective.request.uri"/>)
114   to one or more of the new references sent by the server, where possible.
115</t>
116<t>
117   The server &SHOULD; generate a Location header field (<xref target="RFC7231" x:rel="#header.location" x:fmt=","/>) in the
118   response containing a preferred URI reference for the new permanent URI.
119   The user agent &MAY; use the Location field value for automatic redirection.
120   The server's response payload usually contains a short hypertext note with
121   a hyperlink to the new URI(s).
122</t>
123<t>
124   A 308 response is cacheable by default; i.e., unless otherwise indicated by
125   the method definition or explicit cache controls (see <xref target="RFC7234" x:rel="#heuristic.freshness" x:fmt=","/>).
126</t>
127<x:note>
128  <t>
129    &Note; This status code is similar to 301 (Moved Permanently) (<xref target="RFC7231" x:rel="#status.301" x:fmt=","/>), except
130    that it does not allow changing the request method from POST to GET.
131  </t>
132</x:note>
133
134</section>
135
136<section title="Deployment Considerations" anchor="deployment.considerations">
137<t>
138  <xref target="RFC7231" x:rel="#status.codes"/>
139  requires recipients to treat unknown 3xx status codes the same way as
140  status code 300 (Multiple Choices) (<xref target="RFC7231" x:rel="#status.300" x:fmt=","/>).
141  Thus, servers will not be able to rely on automatic redirection happening
142  similar to status codes 301, 302, or 307.
143</t>
144<t>
145  Therefore, the use of status code 308 is restricted to cases where
146  the server has sufficient confidence in the client's understanding the new
147  code or when a fallback to the semantics of status code 300 is not problematic.
148  Server implementers are advised not to vary the status code based on
149  characteristics of the request, such as the User-Agent header field
150  ("User-Agent Sniffing") &mdash; doing so usually results in code that is both
151  hard to maintain and hard to debug and would also require special attention to caching
152  (i.e., setting a "Vary" response header field, as defined in
153  <xref target="RFC7231" x:fmt="of" x:rel="#header.vary"/>).
154</t>
155<t>
156  Note that many existing HTML-based user agents will emulate a refresh when encountering
157  an HTML &lt;meta&gt; refresh directive (<xref target="HTML" x:fmt="," x:sec="4.2.5.3" x:rel="document-metadata.html#pragma-directives"/>). This can be used as another
158  fallback. For example:
159</t>
160
161<figure>
162  <preamble>Client request:</preamble>
163  <artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
164GET / HTTP/1.1
165Host: example.com
166
167</artwork></figure>
168<figure>
169  <preamble>Server response:</preamble>
170  <artwork type="message/http; msgtype=&#34;response&#34;" x:indent-with="  ">
171HTTP/1.1 308 Permanent Redirect
172Content-Type: text/html; charset=UTF-8
173Location: http://example.com/new
174Content-Length: <x:length-of target="body"/>
175
176<x:span anchor="body">&lt;!DOCTYPE HTML&gt;
177&lt;html&gt;
178   &lt;head&gt;
179      &lt;title&gt;Permanent Redirect&lt;/title&gt;
180      &lt;meta http-equiv="refresh"
181            content="0; url=http://example.com/new"&gt;
182   &lt;/head&gt;
183   &lt;body&gt;
184      &lt;p&gt;
185         The document has been moved to
186         &lt;a href="http://example.com/new"
187         &gt;http://example.com/new&lt;/a&gt;.
188      &lt;/p&gt;
189   &lt;/body&gt;
190&lt;/html&gt;
191</x:span></artwork></figure>
192</section>
193
194<section title="Security Considerations" anchor="security.considerations">
195<t>
196  All security considerations that apply to HTTP redirects apply to the
197  308 status code as well (see <xref target="RFC7231" x:rel="#security.considerations"/>).
198</t>
199<t>
200  Unsecured communication over the Internet is subject to man-in-the-middle
201  modification of messages, including changing status codes or
202  redirect targets.  Use of Transport Layer Security (TLS) is one way to mitigate those attacks.
203  See <xref target="RFC7230" x:rel="#security.considerations"/> for related
204  attacks on authority and message integrity.
205</t>
206</section> 
207
208<section title="IANA Considerations" anchor="iana.considerations">
209<t>
210   The "Hypertext Transfer Protocol (HTTP) Status Code Registry"
211   (defined in <xref target="RFC7231" x:rel="#status.code.registry"/>
212   and located at <eref target="http://www.iana.org/assignments/http-status-codes"/>)
213   has been updated to reference this specification.
214</t>
215<texttable align="left" suppress-title="true" anchor="iana.status.code.registration.table">
216   <ttcol>Value</ttcol>
217   <ttcol>Description</ttcol>
218   <ttcol>Reference</ttcol>
219   <c>308</c>
220   <c>Permanent Redirect</c>
221   <c>
222      <xref target="status.308"/> of this specification
223   </c>
224</texttable>
225</section>
226  </middle>
227  <back>
228 
229<references title="Normative References">
230
231<reference anchor="RFC2119">
232  <front>
233    <title>Key words for use in RFCs to Indicate Requirement Levels</title>
234    <author initials="S." surname="Bradner" fullname="Scott Bradner">
235      <organization>Harvard University</organization>
236      <address><email>sob@harvard.edu</email></address>
237    </author>
238    <date month="March" year="1997"/>
239  </front>
240  <seriesInfo name="BCP" value="14"/>
241  <seriesInfo name="RFC" value="2119"/>
242</reference>
243
244<reference anchor="RFC3986">
245 <front>
246  <title abbrev="URI Generic Syntax">Uniform Resource Identifier (URI): Generic Syntax</title>
247  <author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
248    <organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
249    <address>
250       <email>timbl@w3.org</email>
251       <uri>http://www.w3.org/People/Berners-Lee/</uri>
252    </address>
253  </author>
254  <author initials="R." surname="Fielding" fullname="Roy T. Fielding">
255    <organization abbrev="Day Software">Day Software</organization>
256    <address>
257      <email>fielding@gbiv.com</email>
258      <uri>http://roy.gbiv.com/</uri>
259    </address>
260  </author>
261  <author initials="L." surname="Masinter" fullname="Larry Masinter">
262    <organization abbrev="Adobe Systems">Adobe Systems Incorporated</organization>
263    <address>
264      <email>LMM@acm.org</email>
265      <uri>http://larry.masinter.net/</uri>
266    </address>
267  </author>
268  <date month="January" year="2005"/>
269 </front>
270 <seriesInfo name="STD" value="66"/>
271 <seriesInfo name="RFC" value="3986"/>
272</reference>
273
274
275<reference anchor="RFC7230">
276  <front>
277    <title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
278    <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
279      <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
280      <address><email>fielding@gbiv.com</email></address>
281    </author>
282    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
283      <organization abbrev="greenbytes">greenbytes GmbH</organization>
284      <address><email>julian.reschke@greenbytes.de</email></address>
285    </author>
286    <date month="June" year="2014"/>
287  </front>
288  <seriesInfo name="RFC" value="7230"/>
289  <x:source href="rfc7230.xml" basename="https://svn.tools.ietf.org/svn/wg/httpbis/specs/rfc7230"/>
290</reference>
291
292<reference anchor="RFC7231">
293  <front>
294    <title>Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</title>
295    <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
296      <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
297      <address><email>fielding@gbiv.com</email></address>
298    </author>
299    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
300      <organization abbrev="greenbytes">greenbytes GmbH</organization>
301      <address><email>julian.reschke@greenbytes.de</email></address>
302    </author>
303    <date month="June" year="2014"/>
304  </front>
305  <seriesInfo name="RFC" value="7231"/>
306  <x:source href="rfc7231.xml" basename="https://svn.tools.ietf.org/svn/wg/httpbis/specs/rfc7231"/>
307</reference>
308
309<reference anchor="RFC7234">
310  <front>
311    <title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
312    <author initials="R." surname="Fielding" fullname="Roy T. Fielding" role="editor">
313      <organization abbrev="Adobe">Adobe Systems Incorporated</organization>
314      <address><email>fielding@gbiv.com</email></address>
315    </author>
316    <author initials="M." surname="Nottingham" fullname="Mark Nottingham" role="editor">
317      <organization>Rackspace</organization>
318      <address><email>mnot@mnot.net</email></address>
319    </author>
320    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke" role="editor">
321      <organization abbrev="greenbytes">greenbytes GmbH</organization>
322      <address><email>julian.reschke@greenbytes.de</email></address>
323    </author>
324    <date month="June" year="2014"/>
325  </front>
326  <seriesInfo name="RFC" value="7234"/>
327  <x:source href="rfc7234.xml" basename="https://svn.tools.ietf.org/svn/wg/httpbis/specs/rfc7234"/>
328</reference>
329
330</references>
331
332
333<references title="Informative References">
334<reference anchor='HTML'
335           target='http://www.w3.org/TR/2014/REC-html5-20141028/'>
336  <front>
337    <title>HTML5</title>
338    <author fullname='Ian Hickson' surname='Hickson' initials='I.'/>
339    <author fullname='Robin Berjon' surname='Berjon' initials='R.'/>
340    <author fullname='Steve Faulkner' surname='Faulkner' initials='S.'/>
341    <author fullname='Travis Leithead' surname='Leithead' initials='T.'/>
342    <author fullname='Erika Doyle Navara' surname='Doyle Navara' initials='E.'/>
343    <author fullname='Edward O&apos;Connor' surname='O&apos;Connor' initials='E.'/>
344    <author fullname='Silvia Pfeiffer' surname='Pfeiffer' initials='S.'/>
345    <date year='2014' month='October' day='28'/>
346  </front>
347  <seriesInfo name='W3C Recommendation' value='REC-html5-20141028'/>
348  <annotation>
349    Latest version available at
350    <eref target='http://www.w3.org/TR/html5/'/>.
351  </annotation>
352</reference>
353<!--<reference anchor="RFC7238">
354  <front>
355    <title>The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)</title>
356    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke">
357      <address><email>julian.reschke@greenbytes.de</email></address>
358    </author>
359    <date month="June" year="2014"/>
360  </front>
361  <seriesInfo name="RFC" value="7238"/>
362</reference>-->
363</references>
364
365
366<section title="Acknowledgements" anchor="acknowledgements" numbered="false">
367<t>
368  The definition for the new status code 308 reuses text from
369  the HTTP/1.1 definitions of status codes 301 and 307.
370</t>
371<t>
372  Furthermore, thanks to Ben Campbell, Cyrus Daboo, Adrian Farrell, Eran Hammer-Lahav,
373  Bjoern Hoehrmann, Barry Leiba,
374  Subramanian Moonesamy, Kathleen Moriarty, Peter Saint-Andre,
375  Robert Sparks, and Roy Fielding for feedback on this document.
376</t>
377</section>
378  </back>
379
380</rfc>
Note: See TracBrowser for help on using the repository browser.