Ignore:
Timestamp:
Jul 4, 2012, 12:54:55 PM (7 years ago)
Author:
julian.reschke@…
Message:

Work-in-progress: hyperlink status codes definitions (2xx range)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p2-semantics.html

    r1714 r1715  
    10211021         URI.
    10221022      </p>
    1023       <p id="rfc.section.2.3.4.p.3">The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either
    1024          200 (OK) or 204 (No Content) is the appropriate response status code, depending on whether or not the response includes a
    1025          representation that describes the result.
    1026       </p>
    1027       <p id="rfc.section.2.3.4.p.4">If a resource has been created on the origin server, the response <em class="bcp14">SHOULD</em> be 201 (Created) and contain a representation which describes the status of the request and refers to the new resource, and
    1028          a Location header field (see <a href="#header.location" id="rfc.xref.header.location.1" title="Location">Section&nbsp;9.13</a>).
     1023      <p id="rfc.section.2.3.4.p.3">The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either <a href="#status.200" class="smpl">200 (OK)</a> or <a href="#status.204" class="smpl">204 (No Content)</a> is the appropriate response status code, depending on whether or not the response includes a representation that describes
     1024         the result.
     1025      </p>
     1026      <p id="rfc.section.2.3.4.p.4">If a resource has been created on the origin server, the response <em class="bcp14">SHOULD</em> be <a href="#status.201" class="smpl">201 (Created)</a> and contain a representation which describes the status of the request and refers to the new resource, and a Location header
     1027         field (see <a href="#header.location" id="rfc.xref.header.location.1" title="Location">Section&nbsp;9.13</a>).
    10291028      </p>
    10301029      <p id="rfc.section.2.3.4.p.5">Responses to POST requests are only cacheable when they include explicit freshness information (see <a href="p6-cache.html#calculating.freshness.lifetime" title="Calculating Freshness Lifetime">Section 2.3.1</a> of <a href="#Part6" id="rfc.xref.Part6.4"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>). A cached POST response with a Content-Location header field (see <a href="#header.content-location" id="rfc.xref.header.content-location.1" title="Content-Location">Section&nbsp;9.8</a>) whose value is the effective Request URI <em class="bcp14">MAY</em> be used to satisfy subsequent GET and HEAD requests.
     
    10371036      <p id="rfc.section.2.3.5.p.1">The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation
    10381037         enclosed in the request message payload. A successful PUT of a given representation would suggest that a subsequent GET on
    1039          that same target resource will result in an equivalent representation being returned in a 200 (OK) response. However, there
    1040          is no guarantee that such a state change will be observable, since the target resource might be acted upon by other user agents
    1041          in parallel, or might be subject to dynamic processing by the origin server, before any subsequent GET is received. A successful
    1042          response only implies that the user agent's intent was achieved at the time of its processing by the origin server.
    1043       </p>
    1044       <p id="rfc.section.2.3.5.p.2">If the target resource does not have a current representation and the PUT successfully creates one, then the origin server <em class="bcp14">MUST</em> inform the user agent by sending a 201 (Created) response. If the target resource does have a current representation and that
    1045          representation is successfully modified in accordance with the state of the enclosed representation, then either a 200 (OK)
    1046          or 204 (No Content) response <em class="bcp14">SHOULD</em> be sent to indicate successful completion of the request.
     1038         that same target resource will result in an equivalent representation being returned in a <a href="#status.200" class="smpl">200 (OK)</a> response. However, there is no guarantee that such a state change will be observable, since the target resource might be acted
     1039         upon by other user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent
     1040         GET is received. A successful response only implies that the user agent's intent was achieved at the time of its processing
     1041         by the origin server.
     1042      </p>
     1043      <p id="rfc.section.2.3.5.p.2">If the target resource does not have a current representation and the PUT successfully creates one, then the origin server <em class="bcp14">MUST</em> inform the user agent by sending a <a href="#status.201" class="smpl">201 (Created)</a> response. If the target resource does have a current representation and that representation is successfully modified in accordance
     1044         with the state of the enclosed representation, then either a <a href="#status.200" class="smpl">200 (OK)</a> or <a href="#status.204" class="smpl">204 (No Content)</a> response <em class="bcp14">SHOULD</em> be sent to indicate successful completion of the request.
    10471045      </p>
    10481046      <p id="rfc.section.2.3.5.p.3">Unrecognized header fields <em class="bcp14">SHOULD</em> be ignored (i.e., not saved as part of the resource state).
     
    11001098         location.
    11011099      </p>
    1102       <p id="rfc.section.2.3.6.p.2">A successful response <em class="bcp14">SHOULD</em> be 200 (OK) if the response includes an representation describing the status, 202 (Accepted) if the action has not yet been
    1103          enacted, or 204 (No Content) if the action has been enacted but the response does not include a representation.
     1100      <p id="rfc.section.2.3.6.p.2">A successful response <em class="bcp14">SHOULD</em> be <a href="#status.200" class="smpl">200 (OK)</a> if the response includes an representation describing the status, <a href="#status.202" class="smpl">202 (Accepted)</a> if the action has not yet been enacted, or <a href="#status.204" class="smpl">204 (No Content)</a> if the action has been enacted but the response does not include a representation.
    11041101      </p>
    11051102      <p id="rfc.section.2.3.6.p.3">Bodies on DELETE requests have no defined semantics. Note that sending a body on a DELETE request might cause some existing
     
    11121109      <div id="rfc.iref.t.1"></div>
    11131110      <div id="rfc.iref.m.7"></div>
    1114       <p id="rfc.section.2.3.7.p.1">The TRACE method requests a remote, application-layer loop-back of the request message. The final recipient of the request <em class="bcp14">SHOULD</em> reflect the message received back to the client as the message body of a 200 (OK) response. The final recipient is either
    1115          the origin server or the first proxy to receive a Max-Forwards value of zero (0) in the request (see <a href="#header.max-forwards" id="rfc.xref.header.max-forwards.2" title="Max-Forwards">Section&nbsp;9.14</a>). A TRACE request <em class="bcp14">MUST NOT</em> include a message body.
     1111      <p id="rfc.section.2.3.7.p.1">The TRACE method requests a remote, application-layer loop-back of the request message. The final recipient of the request <em class="bcp14">SHOULD</em> reflect the message received back to the client as the message body of a <a href="#status.200" class="smpl">200 (OK)</a> response. The final recipient is either the origin server or the first proxy to receive a Max-Forwards value of zero (0) in
     1112         the request (see <a href="#header.max-forwards" id="rfc.xref.header.max-forwards.2" title="Max-Forwards">Section&nbsp;9.14</a>). A TRACE request <em class="bcp14">MUST NOT</em> include a message body.
    11161113      </p>
    11171114      <p id="rfc.section.2.3.7.p.2">TRACE allows the client to see what is being received at the other end of the request chain and use that data for testing
     
    17041701         can be omitted (e.g., in the case of a response to a PUT request).
    17051702      </p>
    1706       <p id="rfc.section.4.4.2.p.3">The origin server <em class="bcp14">MUST</em> create the resource(s) before returning the 201 status code. If the action cannot be carried out immediately, the server <em class="bcp14">SHOULD</em> respond with 202 (Accepted) response instead.
     1703      <p id="rfc.section.4.4.2.p.3">The origin server <em class="bcp14">MUST</em> create the resource(s) before returning the 201 status code. If the action cannot be carried out immediately, the server <em class="bcp14">SHOULD</em> respond with <a href="#status.202" class="smpl">202 (Accepted)</a> response instead.
    17071704      </p>
    17081705      <p id="rfc.section.4.4.2.p.4">A 201 response <em class="bcp14">MAY</em> contain an ETag response header field indicating the current value of the entity-tag for the representation of the resource
     
    17261723      <p id="rfc.section.4.4.4.p.1">The representation in the response has been transformed or otherwise modified by a transforming proxy (<a href="p1-messaging.html#intermediaries" title="Intermediaries">Section 2.3</a> of <a href="#Part1" id="rfc.xref.Part1.34"><cite title="HTTP/1.1, part 1: URIs, Connections, and Message Parsing">[Part1]</cite></a>). Note that the behavior of transforming intermediaries is controlled by the no-transform Cache-Control directive (<a href="p6-cache.html#header.cache-control" title="Cache-Control">Section 3.2</a> of <a href="#Part6" id="rfc.xref.Part6.12"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>).
    17271724      </p>
    1728       <p id="rfc.section.4.4.4.p.2">This status code is only appropriate when the response status code would have been 200 (OK) otherwise. When the status code
    1729          before transformation would have been different, the 214 Transformation Applied warn-code (<a href="p6-cache.html#header.warning" title="Warning">Section 3.6</a> of <a href="#Part6" id="rfc.xref.Part6.13"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>) is appropriate.
     1725      <p id="rfc.section.4.4.4.p.2">This status code is only appropriate when the response status code would have been <a href="#status.200" class="smpl">200 (OK)</a> otherwise. When the status code before transformation would have been different, the 214 Transformation Applied warn-code
     1726         (<a href="p6-cache.html#header.warning" title="Warning">Section 3.6</a> of <a href="#Part6" id="rfc.xref.Part6.13"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>) is appropriate.
    17301727      </p>
    17311728      <p id="rfc.section.4.4.4.p.3">Caches <em class="bcp14">MAY</em> use a heuristic (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 2.3.1.1</a> of <a href="#Part6" id="rfc.xref.Part6.14"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>) to determine freshness for 203 responses.
     
    23562353         identified by the effective request URI). The precise semantics of a representation are determined by the type of message
    23572354         (request or response), the request method, the response status code, and the representation metadata. For example, the above
    2358          semantic is true for the representation in any 200 (OK) response to GET and for the representation in any PUT request. A 200
    2359          response to PUT, in contrast, contains either a representation that describes the successful action or a representation of
    2360          the target resource, with the latter indicated by a Content-Location header field with the same value as the effective request
    2361          URI. Likewise, response messages with an error status code usually contain a representation that describes the error and what
    2362          next steps are suggested for resolving it.
     2355         semantic is true for the representation in any <a href="#status.200" class="smpl">200 (OK)</a> response to GET and for the representation in any PUT request. A 200 response to PUT, in contrast, contains either a representation
     2356         that describes the successful action or a representation of the target resource, with the latter indicated by a Content-Location
     2357         header field with the same value as the effective request URI. Likewise, response messages with an error status code usually
     2358         contain a representation that describes the error and what next steps are suggested for resolving it.
    23632359      </p>
    23642360      <p id="rfc.section.7.p.3">Request and Response messages <em class="bcp14">MAY</em> transfer a representation if not otherwise restricted by the request method or response status code. A representation consists
     
    29722968      </p>
    29732969      <div id="rfc.figure.u.50"></div><pre class="inline"><span id="rfc.iref.g.52"></span>  <a href="#header.location" class="smpl">Location</a> = <a href="#abnf.dependencies" class="smpl">URI-reference</a>
    2974 </pre><p id="rfc.section.9.13.p.3">For 201 (Created) responses, the Location is the URI of the new resource which was created by the request. For 3xx responses,
    2975          the location <em class="bcp14">SHOULD</em> indicate the server's preferred URI for automatic redirection to the resource.
     2970</pre><p id="rfc.section.9.13.p.3">For <a href="#status.201" class="smpl">201 (Created)</a> responses, the Location is the URI of the new resource which was created by the request. For 3xx responses, the location <em class="bcp14">SHOULD</em> indicate the server's preferred URI for automatic redirection to the resource.
    29762971      </p>
    29772972      <p id="rfc.section.9.13.p.4">The field value consists of a single URI-reference. When it has the form of a relative reference (<a href="#RFC3986" id="rfc.xref.RFC3986.1"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-4.2">Section 4.2</a>), the final value is computed by resolving it against the effective request URI (<a href="#RFC3986" id="rfc.xref.RFC3986.2"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, <a href="http://tools.ietf.org/html/rfc3986#section-5">Section 5</a>). If the original URI, as navigated to by the user agent, did contain a fragment identifier, and the final value does not,
     
    29902985      </div>
    29912986      <p id="rfc.section.9.13.p.8">There are circumstances in which a fragment identifier in a Location URI would not be appropriate. For instance, when it appears
    2992          in a 201 Created response, where the Location header field specifies the URI for the entire created resource.
     2987         in a <a href="#status.201" class="smpl">201
     2988            (Created)</a> response, where the Location header field specifies the URI for the entire created resource.
    29932989      </p>
    29942990      <div class="note" id="rfc.section.9.13.p.9">
     
    39483944      <p id="rfc.section.C.p.4">This document takes over the Status Code Registry, previously defined in <a href="http://tools.ietf.org/html/rfc2817#section-7.1">Section 7.1</a> of <a href="#RFC2817" id="rfc.xref.RFC2817.3"><cite title="Upgrading to TLS Within HTTP/1.1">[RFC2817]</cite></a>. (<a href="#status.code.registry" title="Status Code Registry">Section&nbsp;4.2</a>)
    39493945      </p>
    3950       <p id="rfc.section.C.p.5">Broadened the definition of 203 (Non-Authoritative Information) to include cases of payload transformations as well. (<a href="#status.203" id="rfc.xref.status.203.3" title="203 Non-Authoritative Information">Section&nbsp;4.4.4</a>)
     3946      <p id="rfc.section.C.p.5">Broadened the definition of <a href="#status.203" class="smpl">203 (Non-Authoritative Information)</a> to include cases of payload transformations as well. (<a href="#status.203" id="rfc.xref.status.203.3" title="203 Non-Authoritative Information">Section&nbsp;4.4.4</a>)
    39513947      </p>
    39523948      <p id="rfc.section.C.p.6">Status codes 301, 302, and 307: removed the normative requirements on both response payloads and user interaction. (<a href="#status.3xx" title="Redirection 3xx">Section&nbsp;4.5</a>)
     
    39563952         the method from POST to GET for status codes 301 and 302. (Sections <a href="#status.301" id="rfc.xref.status.301.3" title="301 Moved Permanently">4.5.2</a>, <a href="#status.302" id="rfc.xref.status.302.3" title="302 Found">4.5.3</a> and <a href="#status.307" id="rfc.xref.status.307.3" title="307 Temporary Redirect">4.5.7</a>)
    39573953      </p>
    3958       <p id="rfc.section.C.p.8">Deprecate 305 Use Proxy status code, because user agents did not implement it. It used to indicate that the target resource
    3959          needs to be accessed through the proxy given by the Location field. The Location field gave the URI of the proxy. The recipient
    3960          was expected to repeat this single request via the proxy. (<a href="#status.305" id="rfc.xref.status.305.3" title="305 Use Proxy">Section&nbsp;4.5.5</a>)
    3961       </p>
    3962       <p id="rfc.section.C.p.9">Define status 426 (Upgrade Required) (this was incorporated from <a href="#RFC2817" id="rfc.xref.RFC2817.4"><cite title="Upgrading to TLS Within HTTP/1.1">[RFC2817]</cite></a>). (<a href="#status.426" id="rfc.xref.status.426.3" title="426 Upgrade Required">Section&nbsp;4.6.15</a>)
     3954      <p id="rfc.section.C.p.8">Deprecate <a href="#status.305" class="smpl">305 (Use Proxy)</a> status code, because user agents did not implement it. It used to indicate that the target resource needs to be accessed through
     3955         the proxy given by the Location field. The Location field gave the URI of the proxy. The recipient was expected to repeat
     3956         this single request via the proxy. (<a href="#status.305" id="rfc.xref.status.305.3" title="305 Use Proxy">Section&nbsp;4.5.5</a>)
     3957      </p>
     3958      <p id="rfc.section.C.p.9">Define status <a href="#status.426" class="smpl">426 (Upgrade Required)</a> (this was incorporated from <a href="#RFC2817" id="rfc.xref.RFC2817.4"><cite title="Upgrading to TLS Within HTTP/1.1">[RFC2817]</cite></a>). (<a href="#status.426" id="rfc.xref.status.426.3" title="426 Upgrade Required">Section&nbsp;4.6.15</a>)
    39633959      </p>
    39643960      <p id="rfc.section.C.p.10">Change ABNF productions for header fields to only define the field value. (<a href="#header.field.definitions" title="Header Field Definitions">Section&nbsp;9</a>)
Note: See TracChangeset for help on using the changeset viewer.