Changeset 2056 for draft-ietf-httpbis/latest/p2-semantics.xml

Timestamp:

Dec 20, 2012, 1:33:38 AM (7 years ago)

Author:

fielding@…

Message:

editorial improvements to 3xx status codes; partly addresses #419

File:

• draft-ietf-httpbis/latest/p2-semantics.xml (modified) (12 diffs)

draft-ietf-httpbis/latest/p2-semantics.xml

@@ -2826 +2826 @@
   <iref primary="true" item="Status Codes Classes" subitem="3xx Redirection" x:for-anchor=""/>
 <t>
-   This class of status code indicates that further action needs to be
-   taken by the user agent in order to fulfill the request.
+   The <x:dfn>3xx (Redirection)</x:dfn> class of status code indicates that
+   further action needs to be taken by the user agent in order to fulfill the
+   request.
 </t>
 <t>
@@ -2909 +2910 @@
   <x:anchor-alias value="300 (Multiple Choices)"/>
 <t>
-   The target resource has more than one
-   representation, each with its own specific location, and reactive
-   negotiation information (&content-negotiation;) is being provided so that
-   the user (or user agent) can select a preferred representation by
-   redirecting its request to that location.
-</t>
-<t>
-   Unless it was a HEAD request, the response &SHOULD; include a representation
-   containing a list of representation metadata and location(s) from
-   which the user or user agent can choose the one most appropriate. Depending
-   upon the format and the capabilities of
-   the user agent, selection of the most appropriate choice &MAY; be
-   performed automatically. However, this specification does not define
-   any standard for such automatic selection.
-</t>
-<t>
-   If the server has a preferred choice of representation, it &SHOULD;
-   include the specific URI for that representation in the <x:ref>Location</x:ref>
-   field; user agents &MAY; use the Location field value for automatic
-   redirection. 
+   The <x:dfn>300 (Multiple Choices)</x:dfn> status code indicates that the
+   target resource has more than one representation, each with its own more
+   specific identifier, and information about the alternatives is being
+   provided so that the user (or user agent) can select a preferred
+   representation by redirecting its request to one or more of those
+   identifiers. In other words, the server desires that the user agent engage
+   in reactive negotiation to select the most appropriate representation(s)
+   for its needs (&content-negotiation;).
+</t>
+<t>
+   For request methods other than HEAD, the server &SHOULD; generate a payload
+   in the 300 response containing a list of representation metadata and URI
+   reference(s) from which the user or user agent can choose the one most
+   preferred. The user agent &MAY; make a selection from that list
+   automatically, depending upon the list format, but this specification does
+   not define a standard for such automatic selection.
+</t>
+<t>
+   If the server has a preferred choice, the server &SHOULD; generate a
+   <x:ref>Location</x:ref> header field containing a preferred choice's URI
+   reference. The user agent &MAY; use the Location field value for automatic
+   redirection.
 </t>
 <t>
@@ -2942 +2945 @@
   <x:anchor-alias value="301 (Moved Permanently)"/>
 <t>
-   The target resource has been assigned a new permanent URI and any
-   future references to this resource &SHOULD; use one of the enclosed
-   URIs.  Clients with link editing capabilities ought to automatically
-   re-link references to the effective request URI to one or more of the new
-   references sent by the server, where possible.
-</t>
-<t>
-   Caches &MAY; use a heuristic (see &p6-heuristic;) to determine 
-   freshness for 301 responses.
-</t>
-<t>
-   The new permanent URI &SHOULD; be given by the <x:ref>Location</x:ref> field
-   in the response. A response payload can contain a short hypertext note with a
-   hyperlink to the new URI(s).
+   The <x:dfn>301 (Moved Permanently)</x:dfn> status code indicates that the
+   target resource has been assigned a new permanent URI and any future
+   references to this resource ought to use one of the enclosed URIs. Clients
+   with link editing capabilities ought to automatically re-link references to
+   the effective request URI to one or more of the new references sent by the
+   server, where possible.
+</t>
+<t>
+   The server &SHOULD; generate a <x:ref>Location</x:ref> header field in the
+   response containing a preferred URI reference for the new permanent URI.
+   The user agent &MAY; use the Location field value for automatic redirection.
+   The server's response payload usually contains a short hypertext note with
+   a hyperlink to the new URI(s).
 </t>
 <x:note>
@@ -2965 +2967 @@
   </t>
 </x:note>
+<t>
+   Caches &MAY; use a heuristic (see &p6-heuristic;) to determine 
+   freshness for 301 responses.
+</t>
 </section>
 
@@ -2972 +2978 @@
   <x:anchor-alias value="302 (Found)"/>
 <t>
-   The target resource resides temporarily under a different URI.
-   Since the redirection might be altered on occasion, the client &SHOULD;
-   continue to use the effective request URI for future requests.
-</t>
-<t>
-   The temporary URI &SHOULD; be given by the <x:ref>Location</x:ref> field in
-   the response. A response payload can contain a short hypertext note with a
-   hyperlink to the new URI(s).
+   The <x:dfn>302 (Found)</x:dfn> status code indicates that the target
+   resource resides temporarily under a different URI. Since the redirection
+   might be altered on occasion, the client ought to continue to use the
+   effective request URI for future requests.
+</t>
+<t>
+   The server &SHOULD; generate a <x:ref>Location</x:ref> header field in the
+   response containing a URI reference for the different URI.
+   The user agent &MAY; use the Location field value for automatic redirection.
+   The server's response payload usually contains a short hypertext note with
+   a hyperlink to the different URI(s).
 </t>
 <x:note>
@@ -2995 +3004 @@
   <x:anchor-alias value="303 (See Other)"/>
 <t>
-   The 303 status code indicates that the server is redirecting the
-   user agent to a different resource, as indicated by a URI in the
-   <x:ref>Location</x:ref> header field, that is intended to provide an indirect
-   response to the original request.  In order to satisfy the original
-   request, a user agent &SHOULD; perform a retrieval request using the
-   Location URI (a GET or HEAD request if using HTTP), which
-   can itself be redirected further, and present the eventual result as an
-   answer to the original request.
-   Note that the new URI in the Location header field is not considered
-   equivalent to the effective request URI. 
-</t>
-<t>
-   This status code is generally applicable to any HTTP method.  It is
+   The <x:dfn>303 (See Other)</x:dfn> status code indicates that the server is
+   redirecting the user agent to a different resource, as indicated by a URI
+   in the <x:ref>Location</x:ref> header field, that is intended to provide an
+   indirect response to the original request. In order to satisfy the original
+   request, a user agent ought to perform a retrieval request using the
+   Location URI (a GET or HEAD request if using HTTP), which can itself be
+   redirected further, and present the eventual result as an answer to the
+   original request. Note that the new URI in the Location header field is not
+   considered equivalent to the effective request URI.
+</t>
+<t>
+   This status code is applicable to any HTTP method.  It is
    primarily used to allow the output of a POST action to redirect
    the user agent to a selected resource, since doing so provides the
@@ -3028 +3036 @@
 <t>
    Except for responses to a HEAD request, the representation of a 303 
-   response &SHOULD; contain a short hypertext note with a hyperlink 
-   to the <x:ref>Location</x:ref> URI.
+   response ought to contain a short hypertext note with a hyperlink to the
+   same URI reference provided in the <x:ref>Location</x:ref> header field.
 </t>
 </section>
@@ -3037 +3045 @@
   <x:anchor-alias value="305 (Use Proxy)"/>
 <t>
-   The 305 status code was defined in a previous version of this specification
-   (see <xref target="changes.from.rfc.2616"/>), and is now deprecated.
+   The <x:dfn>305 (Use Proxy)</x:dfn> status code was defined in a previous
+   version of this specification and is now deprecated
+   (<xref target="changes.from.rfc.2616"/>).
 </t>
 </section>
@@ -3045 +3054 @@
   <iref primary="true" item="306 (Unused) (status code)" x:for-anchor=""/>
 <t>
-   The 306 status code was used in a previous version of the
+   The 306 status code was defined in a previous version of this
    specification, is no longer used, and the code is reserved.
 </t>
@@ -3055 +3064 @@
   <x:anchor-alias value="307 (Temporary Redirect)"/>
 <t>
-   The target resource resides temporarily under a different URI.
-   Since the redirection can change over time, the client &SHOULD;
-   continue to use the effective request URI for future requests.
-</t>
-<t>
-   The temporary URI &SHOULD; be given by the <x:ref>Location</x:ref> field in
-   the response. A response payload can contain a short hypertext note with a
-   hyperlink to the new URI(s).
+   The <x:dfn>307 (Temporary Redirect)</x:dfn> status code indicates that the
+   target resource resides temporarily under a different URI and the
+   user agent &MUST-NOT; change the request method if it performs an automatic
+   redirection to that URI.
+   Since the redirection can change over time, the client ought to continue
+   using the original effective request URI for future requests.
+</t>
+<t>
+   The server &SHOULD; generate a <x:ref>Location</x:ref> header field in the
+   response containing a URI reference for the different URI.
+   The user agent &MAY; use the Location field value for automatic redirection.
+   The server's response payload usually contains a short hypertext note with
+   a hyperlink to the different URI(s).
 </t>
 <x:note>
   <t>
     &Note; This status code is similar to <x:ref>302 (Found)</x:ref>, except
-    that it does not allow rewriting the request method from POST to GET. This
+    that it does not allow changing the request method from POST to GET. This
     specification defines no equivalent counterpart for <x:ref>301 (Moved
     Permanently)</x:ref> (<xref target="status-308"/>,
@@ -3082 +3096 @@
   <iref primary="true" item="Status Codes Classes" subitem="4xx Client Error" x:for-anchor=""/>
 <t>
-   The 4xx class of status code is intended for cases in which the
-   client seems to have erred. Except when responding to a HEAD request,
-   the server &SHOULD; include a representation containing an explanation of the
-   error situation, and whether it is a temporary or permanent
-   condition. These status codes are applicable to any request method.
-   User agents &SHOULD; display any included representation to the user.
+   The <x:dfn>4xx (Client Error)</x:dfn> class of status code indicates that
+   the client seems to have erred. Except when responding to a HEAD request,
+   the server &SHOULD; send a representation containing an explanation of
+   the error situation, and whether it is a temporary or permanent condition.
+   These status codes are applicable to any request method. User agents
+   &SHOULD; display any included representation to the user.
 </t>
 
@@ -3101 +3115 @@
 <section title="402 Payment Required" anchor="status.402">
   <iref primary="true" item="402 Payment Required (status code)" x:for-anchor=""/>
-<t>
-   This code is reserved for future use.
+  <x:anchor-alias value="402 (Payment Required)"/>
+<t>
+   The <x:dfn>402 (Payment Required)</x:dfn> status code is reserved for
+   future use.
 </t>
 </section>