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

Timestamp:

27/12/12 15:58:30 (10 years ago)

Author:

fielding@…

Message:

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

File:

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

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

@@ -718 +718 @@
       <t>If the request is GET or HEAD and the response status code is
          <x:ref>203 (Non-Authoritative Information)</x:ref>, the payload is a
-         potentially modified representation of the target resource; as such,
-         the effective request URI might only act as an identifier for the
-         payload's representation when a request is made via the same chain
-         of intermediaries.</t>
+         potentially modified representation of the
+         <x:ref>target resource</x:ref>; as such, the effective request URI
+         might only act as an identifier for the payload's representation when
+         a request is made via the same chain of intermediaries.</t>
       <t>If the response has a <x:ref>Content-Location</x:ref> header field
          and its field-value is a reference to the same URI as the effective
@@ -864 +864 @@
 <t>
    For example, a representation in the payload of a PUT request
-   (<xref target="PUT"/>) represents the desired state of the target resource
+   (<xref target="PUT"/>) represents the desired state of the <x:ref>target resource</x:ref>
    if the request is successfully applied, whereas a representation in the
    payload of a POST request (<xref target="POST"/>) represents an anonymous
@@ -872 +872 @@
 <t>
    Likewise, the payload of a <x:ref>200 (OK)</x:ref> response to GET
-   (<xref target="GET"/>) contains a representation of the target resource,
+   (<xref target="GET"/>) contains a representation of the <x:ref>target resource</x:ref>,
    as observed at the time of the message origination date
    (<xref target="header.date"/>), whereas the same status code in a response
@@ -940 +940 @@
    (a.k.a., <x:dfn>server-driven negotiation</x:dfn>). Selection is based on
    the available representations for a response (the dimensions over which it
-   might vary; e.g., language, content-coding, etc.) compared to various
+   might vary, such as language, content-coding, etc.) compared to various
    information supplied in the request, including both the explicit
    negotiation fields of <xref target="request.conneg"/> and implicit
@@ -1056 +1056 @@
    HTTP was originally designed to be usable as an interface to distributed
    object systems.  The request method was envisioned as applying
-   semantics to a target resource in much the same way as invoking a defined
+   semantics to a <x:ref>target resource</x:ref> in much the same way as invoking a defined
    method on an identified object would apply semantics. The method token
    is case-sensitive because it might be used as a gateway to object-based
@@ -1239 +1239 @@
 <t>
    The GET method requests transfer of a current representation of
-   the target resource.
+   the <x:ref>target resource</x:ref>.
 </t>
 <t>   
@@ -1313 +1313 @@
    The POST method requests that the origin server accept the
    representation enclosed in the request as data to be processed by the 
-   target resource. For example, POST is frequently used for the following
+   <x:ref>target resource</x:ref>. For example, POST is frequently used for the following
    functions (among others):
   <list style="symbols">
@@ -1370 +1370 @@
   <iref primary="true" item="PUT method" x:for-anchor=""/>
 <t>
-   The PUT method requests that the state of the target resource
+   The PUT method requests that the state of the <x:ref>target resource</x:ref>
    be created or replaced with the state defined by the representation
    enclosed in the request message payload.  A successful PUT of a given
@@ -1498 +1498 @@
 <t>
    The DELETE method requests that the origin server remove the association
-   between the target resource and its current representations or
+   between the <x:ref>target resource</x:ref> and its current representations or
    implementation. In effect, this method is similar to the rm command in
    UNIX: it expresses a deletion operation on the URI mapping of the
@@ -1936 +1936 @@
 <t>
    Conditionals are request header fields that indicate a precondition to be
-   tested before applying the method semantics to the target resource.
+   tested before applying the method semantics to the <x:ref>target resource</x:ref>.
    Each precondition is based on metadata that is expected to change if the
    selected representation of the target resource is changed.  The HTTP/1.1
@@ -2671 +2671 @@
   <list style="hanging">
     <t hangText="GET">
-      a representation of the target resource is sent in the response;
+      a representation of the <x:ref>target resource</x:ref>;
     </t>
     <t hangText="HEAD">
@@ -2763 +2763 @@
    has successfully fulfilled the request and that there is no additional
    content to send in the response payload body. Metadata in the response
-   header fields refer to the target resource and its current representation
+   header fields refer to the <x:ref>target resource</x:ref> and its current representation
    after the requested action.
 </t>
@@ -2911 +2911 @@
 <t>
    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
+   <x:ref>target resource</x:ref> 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
@@ -2946 +2946 @@
 <t>
    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.
+   <x:ref>target resource</x:ref> 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>
@@ -3023 +3023 @@
 </t>
 <t>
-   A 303 response to a GET request indicates that the requested
-   resource does not have a representation of its own that can be
-   transferred by the server over HTTP.  The <x:ref>Location</x:ref> URI
-   indicates a resource that is descriptive of the target resource, such that
-   the follow-on representation might be useful to recipients without
-   implying that it adequately represents the target resource.
-   Note that answers to the questions of what can be represented, what
-   representations are adequate, and what might be a useful description
-   are outside the scope of HTTP and thus entirely determined by the
-   URI owner(s).
+   A 303 response to a GET request indicates that the
+   <x:ref>target resource</x:ref> resource does not have a representation of
+   its own that can be transferred by the server over HTTP.
+   The <x:ref>Location</x:ref> URI identifies a resource that is descriptive
+   of the target resource, such that the follow-on representation might be
+   useful to recipients without implying that it adequately represents the
+   target resource. Note that answers to the questions of what can be
+   represented, what representations are adequate, and what might be a useful
+   description are outside the scope of HTTP and thus entirely determined by
+   the URI owner(s).
 </t>
 <t>
@@ -3065 +3065 @@
 <t>
    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.
+   <x:ref>target resource</x:ref> 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.
@@ -3108 +3108 @@
   <x:anchor-alias value="400 (Bad Request)"/>
 <t>
-   The server cannot or will not process the request, due to a client error (e.g.,
-   malformed syntax).
+   The <x:dfn>400 (Bad Request)</x:dfn> status code indicates that the server
+   cannot or will not process the request because the received syntax is
+   invalid, nonsensical, or exceeds some limitation on what the server is
+   willing to process.
 </t>
 </section>
@@ -3126 +3128 @@
   <x:anchor-alias value="403 (Forbidden)"/>
 <t>
-   The server understood the request, but refuses to authorize it. Providing
-   different user authentication credentials might be successful, but any
-   credentials that were provided in the request are insufficient. The request
-   &SHOULD-NOT; be repeated with the same credentials.
-</t>
-<t>
-   If the request method was not HEAD and the server wishes to make
-   public why the request has not been fulfilled, it &SHOULD; describe the
-   reason for the refusal in the representation.  If the server does not wish to
-   make this information available to the client, the status code <x:ref>404
-   (Not Found)</x:ref> &MAY; be used instead.
+   The <x:dfn>403 (Forbidden)</x:dfn> status code indicates that the origin
+   server understood the request but refuses to authorize it.
+   A server that wishes to make public why the request has been forbidden
+   can describe that reason in the response payload (if any).
+</t>
+<t>
+   If authentication credentials were provided in the request, the origin
+   server considers them insufficient to grant access.
+   The client &SHOULD-NOT; repeat the request with the same credentials.
+   The client &MAY; repeat the request with new or different credentials.
+   However, a request might be forbidden for reasons unrelated to the
+   credentials.
+</t>
+<t>
+   An origin server that wishes to "hide" the current existence of a forbidden
+   <x:ref>target resource</x:ref> &MAY; instead respond with a status
+   code of <x:ref>404 (Not Found)</x:ref>.
 </t>
 </section>
@@ -3144 +3152 @@
   <x:anchor-alias value="404 (Not Found)"/>
 <t>
-   The server has not found anything matching the effective request URI. No
-   indication is given of whether the condition is temporary or
-   permanent. The <x:ref>410 (Gone)</x:ref> status code &SHOULD; be used if the server
-   knows, through some internally configurable mechanism, that an old
-   resource is permanently unavailable and has no forwarding address.
-   This status code is commonly used when the server does not wish to
-   reveal exactly why the request has been refused, or when no other
-   response is applicable.
+   The <x:dfn>404 (Not Found)</x:dfn> status code indicates that the origin
+   server did not find a current representation for the
+   <x:ref>target resource</x:ref> or is not willing to disclose that one
+   exists. A 404 status does not indicate whether this lack of representation
+   is temporary or permanent; the <x:ref>410 (Gone)</x:ref> status code is
+   preferred over 404 if the origin server knows, presumably through some
+   configurable means, that the condition is likely to be permanent.
 </t>
 </section>
@@ -3159 +3166 @@
   <x:anchor-alias value="405 (Method Not Allowed)"/>
 <t>
-   The method specified in the request-line is not allowed for the target
-   resource. The response &MUST; include an <x:ref>Allow</x:ref> header field
-   containing a list of valid methods for the requested resource.
+   The <x:dfn>405 (Method Not Allowed)</x:dfn> status code indicates that the
+   method specified in the request-line is not allowed by the origin server
+   for the <x:ref>target resource</x:ref>. The origin server &MUST; generate
+   an <x:ref>Allow</x:ref> header field in the response containing a list of
+   valid methods for the requested resource.
 </t>
 </section>
@@ -3169 +3178 @@
   <x:anchor-alias value="406 (Not Acceptable)"/>
 <t>
-   The resource identified by the request is only capable of generating
-   response representations which have content characteristics not acceptable
-   according to the <x:ref>Accept</x:ref> and Accept-* header fields sent in
-   the request.
-</t>
-<t>
-   Unless it was a HEAD request, the response &SHOULD; include a representation
-   containing a list of available representation characteristics 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>
-<x:note>
-  <t>
-    &Note; HTTP/1.1 servers are allowed to send responses which are
-    not acceptable according to the accept header fields sent in the
-    request. In some cases, this might even be preferable to sending a
-    406 response. User agents are encouraged to inspect the header fields of
-    an incoming response to determine if it is acceptable.
-  </t>
-</x:note>
-<t>
-   If the response could be unacceptable, a user agent &SHOULD;
-   temporarily stop receipt of more data and query the user for a
-   decision on further actions.
+   The <x:dfn>406 (Not Acceptable)</x:dfn> status code indicates that the
+   <x:ref>target resource</x:ref> does not have a current representation which
+   would be acceptable to the user agent, according to the
+   <x:ref>proactive negotiation</x:ref> header fields received in the request
+   (<xref target="request.conneg"/>), and the server is unwilling to supply a
+   default representation.
+</t>
+<t>
+   The server &SHOULD; generate a payload containing a list of available
+   representation characteristics and corresponding resource identifiers from
+   which the user or user agent can choose the one most appropriate.
+   A user agent &MAY; automatically select the most appropriate choice from
+   that list. However, this specification does not define any standard for
+   such automatic selection. [The original proposal for 406 defined the
+   Alternates header field as providing a list of alternative representations,
+   such that it would be available for responses to the HEAD method, but lack
+   of deployment led to Alternates being dropped from the specification.]
 </t>
 </section>
@@ -3201 +3200 @@
 <section title="408 Request Timeout" anchor="status.408">
   <iref primary="true" item="408 Request Timeout (status code)" x:for-anchor=""/>
-<t>
-   The server did not receive a complete request message within the time that
-   it was prepared to wait. If the client has sent a request, it &MAY; repeat
-   that request, possibly on a new connection if the server indicates that the
-   present connection is being closed.
+  <x:anchor-alias value="408 (Request Timeout)"/>
+<t>
+   The <x:dfn>408 (Request Timeout)</x:dfn> status code indicates
+   that the server did not receive a complete request message within the time
+   that it was prepared to wait. Since the only reason to send this message
+   is if the server has decided to close the connection, the server &SHOULD;
+   indicate that intent with the <x:ref>close</x:ref> connection option
+   (&header-connection;). If the client has an outstanding request in transit,
+   the client &MAY; repeat that request on a new connection.
 </t>
 </section>
@@ -3213 +3216 @@
   <x:anchor-alias value="409 (Conflict)"/>
 <t>
-   The request could not be completed due to a conflict with the current
-   state of the resource. This code is only allowed in situations where
-   it is expected that the user might be able to resolve the conflict
-   and resubmit the request. The payload &SHOULD; include enough
-   information for the user to recognize the source of the conflict.
-   Ideally, the response representation would include enough information for the
-   user or user agent to fix the problem; however, that might not be
-   possible and is not required.
+   The <x:dfn>409 (Conflict)</x:dfn> status code indicates that the request
+   could not be completed due to a conflict with the current state of the
+   resource. This code is only reasonable in situations where it is expected
+   that the user might be able to resolve the conflict and resubmit the
+   request. The server &SHOULD; generate a payload that includes enough
+   information for the user to recognize the source of the conflict. Ideally,
+   the response would include enough information for the user or user agent to
+   fix the problem; however, that might not be possible and is not required.
 </t>
 <t>
@@ -3237 +3240 @@
   <x:anchor-alias value="410 (Gone)"/>
 <t>
-   The target resource is no longer available at the server and no
-   forwarding address is known. This condition is expected to be
-   considered permanent. Clients with link editing capabilities &SHOULD;
-   delete references to the effective request URI after user approval. If the
-   server does not know, or has no facility to determine, whether or not
-   the condition is permanent, the status code <x:ref>404 (Not Found)</x:ref>
-   &SHOULD; be used instead.
+   The <x:dfn>410 (Gone)</x:dfn> status code indicates that access to the
+   <x:ref>target resource</x:ref> is no longer available at the origin
+   server and that this condition is likely to be permanent. If the origin
+   server does not know, or has no facility to determine, whether or not the
+   condition is permanent, the status code <x:ref>404 (Not Found)</x:ref>
+   ought to be used instead.
 </t>
 <t>
@@ -3251 +3253 @@
    remote links to that resource be removed. Such an event is common for
    limited-time, promotional services and for resources belonging to
-   individuals no longer working at the server's site. It is not
+   individuals no longer associated with the origin server's site. It is not
    necessary to mark all permanently unavailable resources as "gone" or
    to keep the mark for any length of time &mdash; that is left to the
@@ -3266 +3268 @@
   <x:anchor-alias value="411 (Length Required)"/>
 <t>
-   The server refuses to accept the request without a defined
-   <x:ref>Content-Length</x:ref>. The client &MAY; repeat the request if it
-   adds a valid Content-Length header field containing the length of the
-   message body in the request message.
-</t>
-</section>
-
-<section title="413 Request Representation Too Large" anchor="status.413">
-  <iref primary="true" item="413 Request Representation Too Large (status code)" x:for-anchor=""/>
-<t>
-   The server is refusing to process a request because the request
-   representation is larger than the server is willing or able to process. The
-   server &MAY; close the connection to prevent the client from continuing
+   The <x:dfn>411 (Length Required)</x:dfn> status code indicates that the
+   server refuses to accept the request without a defined
+   <x:ref>Content-Length</x:ref> (&header-content-length;).
+   The client &MAY; repeat the request if it adds a valid Content-Length
+   header field containing the length of the message body in the request
+   message.
+</t>
+</section>
+
+<section title="413 Request Payload Too Large" anchor="status.413">
+  <iref primary="true" item="413 Request Payload Too Large (status code)" x:for-anchor=""/>
+  <x:anchor-alias value="413 (Request Payload Too Large)"/>
+<t>
+   The <x:dfn>413 (Request Payload Too Large)</x:dfn> status code indicates
+   that the server is refusing to process a request because the request
+   payload is larger than the server is willing or able to process.
+   The server &MAY; close the connection to prevent the client from continuing
    the request.
 </t>
 <t>
-   If the condition is temporary, the server &SHOULD; include a
-   <x:ref>Retry-After</x:ref> header field to indicate that it is temporary and
-   after what time the client &MAY; try again.
+   If the condition is temporary, the server &SHOULD; generate a
+   <x:ref>Retry-After</x:ref> header field to indicate that it is temporary
+   and after what time the client &MAY; try again.
 </t>
 </section>
@@ -3292 +3298 @@
   <x:anchor-alias value="414 (URI Too Long)"/>
 <t>
-   The server is refusing to service the request because the effective request URI
-   is longer than the server is willing to interpret. This rare
-   condition is only likely to occur when a client has improperly
-   converted a POST request to a GET request with long query
-   information, when the client has descended into a URI "black hole" of
+   The <x:dfn>414 (URI Too Long)</x:dfn> status code indicates that the server
+   is refusing to service the request because the
+   request-target (&request-target;) is longer than the server is willing to
+   interpret. This rare condition is only likely to occur when a client has
+   improperly converted a POST request to a GET request with long query
+   information, when the client has descended into a "black hole" of
    redirection (e.g., a redirected URI prefix that points to a suffix of
    itself), or when the server is under attack by a client attempting to
-   exploit security holes present in some servers using fixed-length
-   buffers for reading or manipulating the request-target.
+   exploit security holes present in some servers using fixed-length buffers
+   for reading or manipulating the request-target.
 </t>
 </section>
@@ -3308 +3315 @@
   <x:anchor-alias value="415 (Unsupported Media Type)"/>
 <t>
-   The server is refusing to service the request because the request
-   payload is in a format not supported by this request method on the
-   target resource. The format problem might be due to the request's
-   indicated <x:ref>Content-Type</x:ref> or <x:ref>Content-Encoding</x:ref>,
-   or as a result of inspecting the data directly.
+   The <x:dfn>415 (Unsupported Media Type)</x:dfn> status code indicates that
+   the origin server is refusing to service the request because the payload is
+   in a format not supported by the <x:ref>target resource</x:ref> for this
+   method. The format problem might be due to the request's indicated
+   <x:ref>Content-Type</x:ref> or <x:ref>Content-Encoding</x:ref>, or as a
+   result of inspecting the data directly.
 </t>
 </section>
@@ -3320 +3328 @@
   <x:anchor-alias value="417 (Expectation Failed)"/>
 <t>
-   The expectation given in an <x:ref>Expect</x:ref> header field (see
-   <xref target="header.expect"/>) could not be met by this server, or, if the
-   server is a proxy, the server has unambiguous evidence that the request
-   could not be met by the next-hop server.
+   The <x:dfn>417 (Expectation Failed)</x:dfn> status code indicates that the
+   expectation given in the request's <x:ref>Expect</x:ref> header field
+   (<xref target="header.expect"/>) could not be met by at least one of the
+   inbound servers.
 </t>
 </section>
@@ -3331 +3339 @@
   <x:anchor-alias value="426 (Upgrade Required)"/>
 <t>
-   The request can not be completed without a prior protocol upgrade. This
-   response &MUST; include an <x:ref>Upgrade</x:ref> header field
-   (&header-upgrade;) specifying the required protocols.
+   The <x:dfn>426 (Upgrade Required)</x:dfn> status code indicates that the
+   server refuses to perform the request using the current protocol but might
+   be willing to do so after the client upgrades to a different protocol.
+   The server &MUST; send an <x:ref>Upgrade</x:ref> header field in a 426
+   response to indicate the required protocol(s) (&header-upgrade;).
 </t>
 <figure>
@@ -3346 +3356 @@
 <x:span anchor="s426body">This service requires use of the HTTP/3.0 protocol.
 </x:span></artwork></figure>
-<t>
-   The server &SHOULD; include a message body in the 426 response which
-   indicates in human readable form the reason for the error and describes any
-   alternative courses which might be available to the user.
-</t>
 </section>
 </section>
@@ -3360 +3365 @@
   <iref primary="true" item="Status Codes Classes" subitem="5xx Server Error" x:for-anchor=""/>
 <t>
-   Response status codes beginning with the digit "5" indicate cases in
-   which the server is aware that it has erred or is incapable of
-   performing the request. Except when responding to a HEAD request, the
+   The <x:dfn>5xx (Server Error)</x:dfn> class of status code indicates that
+   the server is aware that it has erred or is incapable of
+   performing the requested method. 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
@@ -3463 +3468 @@
    information about the response which cannot be placed in the status-line.
    These header fields give information about the server and about
-   further access to the target resource (&effective-request-uri;).
+   further access to the <x:ref>target resource</x:ref>.
 </t>
 
@@ -3792 +3797 @@
 <t><iref primary="true" item="selected representation"/>
    We use the term "<x:dfn>selected representation</x:dfn>" to refer to the
-   the current representation of a target resource that would have been
+   the current representation of the <x:ref>target resource</x:ref> that would have been
    selected in a successful response if the same request had used the
    method GET and excluded any conditional request header fields.
@@ -3874 +3879 @@
 <t>
    The remaining response header fields provide more information about
-   the target resource for potential use in later requests.
+   the <x:ref>target resource</x:ref> for potential use in later requests.
 </t>
 <texttable align="left">
@@ -3889 +3894 @@
 <t>
    The "Allow" header field lists the set of methods advertised as
-   supported by the target resource. The purpose of this field is strictly to
+   supported by the <x:ref>target resource</x:ref>. The purpose of this field is strictly to
    inform the recipient of valid request methods associated with the resource.
 </t>
@@ -4254 +4259 @@
    </c>
    <c>413</c>
-   <c>Request Representation Too Large</c>
+   <c>Request Payload Too Large</c>
    <c>
       <xref target="status.413"/>
@@ -4813 +4818 @@
   <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p1-messaging-&ID-VERSION;"/>
   <x:source href="p1-messaging.xml" basename="p1-messaging">
+    <x:defines>close</x:defines>
     <x:defines>Connection</x:defines>
     <x:defines>Content-Length</x:defines>