Ignore:
Timestamp:
18/09/12 23:52:32 (10 years ago)
Author:
fielding@…
Message:

Rewrite the "identifying a representation" and considerations for
new status codes to be more concise and consistent.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r1905 r1907  
    339339   for resolving it.
    340340</t>
     341
     342<section title="Payload Header Fields" anchor="payload.header.fields">
    341343<t>
    342344   Header fields that specifically describe the payload, rather than the
    … …  
    355357</section>
    356358
    357 <section title="Associating a Representation with its Resource" anchor="associating.representation.with.resource">
    358 <t>
    359    It is sometimes necessary to determine an identifier for the resource
    360    associated with a representation.
    361 </t>
    362 <t>
    363    An HTTP request representation, when present, is always associated with an
    364    anonymous (i.e., unidentified) resource.
    365 </t>
    366 <t>
    367    In the common case, an HTTP response is a representation of the target
    368    resource (see &effective-request-uri;). However, this is not always the
    369    case. To determine the URI of the resource a response is associated with,
    370    the following rules are used (with the first applicable one being selected):
    371 </t>
    372 <t><list style="numbers">
    373    <t>If the response status code is <x:ref>200 (OK)</x:ref> or <x:ref>203
    374    (Non-Authoritative Information)</x:ref> and the request method was GET,
    375    the response payload is a representation of the target resource.</t>
    376    <t>If the response status code is <x:ref>204 (No Content)</x:ref>,
    377    <x:ref>206 (Partial Content)</x:ref>, or <x:ref>304 (Not Modified)</x:ref>
    378    and the request method was GET or HEAD, the response payload is a partial
    379    representation of the target resource.</t>
    380    <t>If the response has a <x:ref>Content-Location</x:ref> header field, and
    381    that URI is the same as the effective request URI, the response payload is a
    382    representation of the target resource.</t>
    383    <t>If the response has a <x:ref>Content-Location</x:ref> header field, and
    384    that URI is not the same as the effective request URI, then the response
    385    asserts that its payload is a representation of the resource identified by
    386    the Content-Location URI. However, such an assertion cannot be trusted unless
    387    it can be verified by other means (not defined by HTTP).</t>
    388    <t>Otherwise, the response is a representation of an anonymous (i.e.,
    389    unidentified) resource.</t>
    390 </list></t>
    391 <t>
    392   <cref anchor="TODO-req-uri">
    393    The comparison function is going to have to be defined somewhere,
    394    because we already need to compare URIs for things like cache invalidation.</cref>
    395 </t>
     359<section title="Identifying the Payload" anchor="identifying.payload">
     360<t>
     361   When a complete or partial representation is transferred in a message
     362   payload, it is often desirable for the sender to supply, or the recipient
     363   to determine, an identifier for the resource corresponding to that
     364   representation.
     365</t>
     366<t>
     367   The following rules are used to determine such a URI for the payload of a
     368   request message:
     369   <list style="symbols">
     370      <t>If the request has a <x:ref>Content-Location</x:ref> header field,
     371         then the sender asserts that the payload is a representation of the
     372         resource identified by the Content-Location field-value. However,
     373         such an assertion cannot be trusted unless it can be verified by
     374         other means (not defined by HTTP). The information might still be
     375         useful for revision history links.</t>
     376      <t>Otherwise, the payload is unidentified.</t>
     377   </list>
     378</t>
     379<t>
     380   The following rules, to be applied in order until a match is found, are
     381   used to determine such a URI for the payload of a response message:
     382   <list style="numbers">
     383      <t>If the request is GET or HEAD and the response status code is
     384         <x:ref>200 (OK)</x:ref>,
     385         <x:ref>204 (No Content)</x:ref>,
     386         <x:ref>206 (Partial Content)</x:ref>, or
     387         <x:ref>304 (Not Modified)</x:ref>,
     388         the payload's identifier is the effective request URI
     389         (&effective-request-uri;).</t>
     390      <t>If the request is GET or HEAD and the response status code is
     391         <x:ref>203 (Non-Authoritative Information)</x:ref>, the payload is a
     392         potentially modified representation of the target resource; as such,
     393         the effective request URI might only act as an identifier for the
     394         payload's representation when a request is made via the same chain
     395         of intermediaries.</t>
     396      <t>If the response has a <x:ref>Content-Location</x:ref> header field
     397         and its field-value is a reference to the same URI as the effective
     398         request URI, the payload's identifier is the effective request URI.</t>
     399      <t>If the response has a <x:ref>Content-Location</x:ref> header field
     400         and its field-value is a reference to a URI different from the
     401         effective request URI, then the sender asserts that the payload is a
     402         representation of the resource identified by the Content-Location
     403         field-value. However, such an assertion cannot be trusted unless
     404         it can be verified by other means (not defined by HTTP).</t>
     405      <t>Otherwise, the payload is unidentified.</t>
     406   </list>
     407</t>
     408</section>
    396409</section>
    397410
    … …  
    41254138<section title="Considerations for New Status Codes" anchor="considerations.for.new.status.codes">
    41264139<t>
    4127    When it is necessary to express new semantics for a HTTP response that
    4128    aren't specific to a single application or media type, and currently defined
    4129    status codes are inadequate, a new status code can be registered.
    4130 </t>
    4131 <t>
    4132    HTTP status codes are generic; that is, they are potentially applicable to
     4140   When it is necessary to express semantics for a response that are not
     4141   defined by current status codes, a new status code can be registered.
     4142   HTTP status codes are generic; they are potentially applicable to
    41334143   any resource, not just one particular media type, "type" of resource, or
    4134    application. As such, it is preferred that new HTTP status codes be
    4135    registered in a document that isn't specific to a single application, so
    4136    that this is clear.
    4137 </t>
    4138 <t>
    4139    Definitions of new HTTP status codes typically explain the request
    4140    conditions that produce a response containing the status code (e.g.,
    4141    combinations of request header fields and/or method(s)), along with any
    4142    interactions with response header fields (e.g., those that are required,
    4143    those that modify the semantics of the response).
    4144 </t>
    4145 <t>
    4146    New HTTP status codes are required to fall under one of the categories
     4144   application. As such, it is preferred that new status codes be
     4145   registered in a document that isn't specific to a single application.
     4146</t>
     4147<t>
     4148   New status codes are required to fall under one of the categories
    41474149   defined in <xref target="status.codes"/>. To allow existing parsers to
    41484150   properly handle them, new status codes cannot disallow a response body,
    4149    although they can mandate a zero-length response body. They can require the
    4150    presence of one or more particular HTTP response header field(s).
    4151 </t>
    4152 <t>
    4153    Likewise, their definitions can specify that caches are allowed to use
    4154    heuristics to determine their freshness (see &caching;; by default, it is
    4155    not allowed), and can define how to determine the resource which they
    4156    carry a representation for (see <xref
    4157    target="associating.representation.with.resource"/>; by default,
    4158    it is anonymous).
     4151   although they can mandate a zero-length response body.
     4152</t>
     4153<t>
     4154   A definition for a new status code ought to explain the request
     4155   conditions that produce a response containing that status code (e.g.,
     4156   combinations of request header fields and/or method(s)) along with any
     4157   dependencies on response header fields (e.g., what fields are required
     4158   and what fields can modify the semantics). A response that can transfer a
     4159   payload ought to specify expected cache behavior (e.g., cacheability and
     4160   freshness criteria, as described in &caching;) and whether the payload has
     4161   any implied association with an identified resource
     4162   (<xref target="identifying.payload"/>).
    41594163</t>
    41604164</section>
Note: See TracChangeset for help on using the changeset viewer.