Changeset 1925 for draft-ietf-httpbis


Ignore:
Timestamp:
01/10/12 08:58:32 (11 years ago)
Author:
fielding@…
Message:

Clarify that interpretation of Content-Location also depends on status code

Location:
draft-ietf-httpbis/latest
Files:
2 edited

Legend:

Unmodified
Added
Removed

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

    r1924 r1925  
    600600                     </li>
    601601                     <li><a href="#rfc.section.3.1.4">3.1.4</a>&nbsp;&nbsp;&nbsp;<a href="#identification">Identification</a><ul>
    602                            <li><a href="#rfc.section.3.1.4.1">3.1.4.1</a>&nbsp;&nbsp;&nbsp;<a href="#identifying.payload">Identifying the Payload</a></li>
     602                           <li><a href="#rfc.section.3.1.4.1">3.1.4.1</a>&nbsp;&nbsp;&nbsp;<a href="#identifying.payload">Identifying a Representation</a></li>
    603603                           <li><a href="#rfc.section.3.1.4.2">3.1.4.2</a>&nbsp;&nbsp;&nbsp;<a href="#header.content-location">Content-Location</a></li>
    604604                        </ul>
    … …  
    881881      </p>
    882882      <p id="rfc.section.3.p.2">For the purposes of HTTP, a <dfn>representation</dfn> is information that reflects the current or desired state of a given resource, in a format that can be readily communicated
    883          via the protocol, consisting of a set of metadata (representation header fields) and a potentially unbounded stream of octets
    884          (representation data).
     883         via the protocol, consisting of a set of representation metadata and a potentially unbounded stream of representation data.
    885884      </p>
    886885      <h2 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1</a>&nbsp;<a id="representation.metadata" href="#representation.metadata">Representation Metadata</a></h2>
    … …  
    11061105      </p>
    11071106      <h3 id="rfc.section.3.1.4"><a href="#rfc.section.3.1.4">3.1.4</a>&nbsp;<a id="identification" href="#identification">Identification</a></h3>
    1108       <h4 id="rfc.section.3.1.4.1"><a href="#rfc.section.3.1.4.1">3.1.4.1</a>&nbsp;<a id="identifying.payload" href="#identifying.payload">Identifying the Payload</a></h4>
     1107      <h4 id="rfc.section.3.1.4.1"><a href="#rfc.section.3.1.4.1">3.1.4.1</a>&nbsp;<a id="identifying.payload" href="#identifying.payload">Identifying a Representation</a></h4>
    11091108      <p id="rfc.section.3.1.4.1.p.1">When a complete or partial representation is transferred in a message payload, it is often desirable for the sender to supply,
    1110          or the recipient to determine, an identifier for the resource corresponding to that representation.
     1109         or the recipient to determine, an identifier for a resource corresponding to that representation.
    11111110      </p>
    11121111      <p id="rfc.section.3.1.4.1.p.2">The following rules are used to determine such a URI for the payload of a request message: </p>
    … …  
    11381137      <div id="rfc.iref.c.6"></div>
    11391138      <h4 id="rfc.section.3.1.4.2"><a href="#rfc.section.3.1.4.2">3.1.4.2</a>&nbsp;<a id="header.content-location" href="#header.content-location">Content-Location</a></h4>
    1140       <p id="rfc.section.3.1.4.2.p.1">The "Content-Location" header field supplies a URI that can be used as a specific identifier for the representation in this
    1141          message. In other words, if one were to perform a GET on this URI at the time of this message's generation, then a <a href="#status.200" class="smpl">200 (OK)</a> response would contain the same representation that is enclosed as payload in this message.
     1139      <p id="rfc.section.3.1.4.2.p.1">The "Content-Location" header field references a URI that can be used as a specific identifier for the representation in this
     1140         message payload. In other words, if one were to perform a GET on this URI at the time of this message's generation, then a <a href="#status.200" class="smpl">200 (OK)</a> response would contain the same representation that is enclosed as payload in this message.
    11421141      </p>
    11431142      <div id="rfc.figure.u.14"></div><pre class="inline"><span id="rfc.iref.g.14"></span>  <a href="#header.content-location" class="smpl">Content-Location</a> = <a href="#imported.abnf" class="smpl">absolute-URI</a> / <a href="#imported.abnf" class="smpl">partial-URI</a>
    … …  
    11451144         body parts in <a href="http://tools.ietf.org/html/rfc2557#section-4">Section 4</a> of <a href="#RFC2557" id="rfc.xref.RFC2557.1"><cite title="MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)">[RFC2557]</cite></a>. However, its appearance in an HTTP message has some special implications for HTTP recipients.
    11461145      </p>
    1147       <p id="rfc.section.3.1.4.2.p.4">If Content-Location is included in a response message and its value is the same as the effective request URI, then the response
    1148          payload <em class="bcp14">SHOULD</em> be considered a current representation of that resource. For a GET or HEAD request, this is the same as the default semantics
     1146      <p id="rfc.section.3.1.4.2.p.4">If Content-Location is included in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response message and its value refers (after conversion to absolute form) to a URI that is the same as the effective request
     1147         URI, then the response payload <em class="bcp14">SHOULD</em> be considered a current representation of that resource. For a GET or HEAD request, this is the same as the default semantics
    11491148         when no Content-Location is provided by the server. For a state-changing request like PUT or POST, it implies that the server's
    11501149         response contains the new representation of that resource, thereby distinguishing it from representations that might only
    … …  
    11521151         need for a subsequent GET request.
    11531152      </p>
    1154       <p id="rfc.section.3.1.4.2.p.5">If Content-Location is included in a response message and its value differs from the effective request URI, then the origin
    1155          server is informing recipients that this representation has its own, presumably more specific, identifier. For a GET or HEAD
    1156          request, this is an indication that the effective request URI identifies a resource that is subject to content negotiation
    1157          and the selected representation for this response can also be found at the identified URI. For other methods, such a Content-Location
    1158          indicates that this representation contains a report on the action's status and the same report is available (for future access
    1159          with GET) at the given URI. For example, a purchase transaction made via a POST request might include a receipt document as
    1160          the payload of the <a href="#status.200" class="smpl">200 (OK)</a> response; the Content-Location value provides an identifier for retrieving a copy of that same receipt in the future.
    1161       </p>
     1153      <p id="rfc.section.3.1.4.2.p.5">If Content-Location is included in a <a href="#status.2xx" class="smpl">2xx (Successful)</a> response message and its field-value refers to a URI that differs from the effective request URI, then the origin server claims
     1154         that the field-value is an identifier for the payload's representation. Such a claim can only be trusted if both identifiers
     1155         share the same resource owner, which cannot be programmatically determined via HTTP.
     1156      </p>
     1157      <ul>
     1158         <li>For a response to a GET or HEAD request, this is an indication that the effective request URI identifies a resource that is
     1159            subject to content negotiation and the Content-Location field-value is a more specific identifier for the selected representation.
     1160         </li>
     1161         <li>For a <a href="#status.201" class="smpl">201 (Created)</a> response to a state-changing method, a Content-Location field-value that is identical to the <a href="#header.location" class="smpl">Location</a> field-value indicates that this payload is a current representation of the newly created resource.
     1162         </li>
     1163         <li>Otherwise, such a Content-Location indicates that this payload is a representation reporting on the requested action's status
     1164            and that the same report is available (for future access with GET) at the given URI. For example, a purchase transaction made
     1165            via a POST request might include a receipt document as the payload of the <a href="#status.200" class="smpl">200 (OK)</a> response; the Content-Location field-value provides an identifier for retrieving a copy of that same receipt in the future.
     1166         </li>
     1167      </ul>
    11621168      <p id="rfc.section.3.1.4.2.p.6">If Content-Location is included in a request message, then it <em class="bcp14">MAY</em> be interpreted by the origin server as an indication of where the user agent originally obtained the content of the enclosed
    11631169         representation (prior to any subsequent modification of the content by that user agent). In other words, the user agent is
    … …  
    11741180         to respond to later requests on that Content-Location URI.
    11751181      </p>
    1176       <p id="rfc.section.3.1.4.2.p.9">If the Content-Location value is a partial URI, the partial URI is interpreted relative to the effective request URI.</p>
    11771182      <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a>&nbsp;<a id="representation.data" href="#representation.data">Representation Data</a></h2>
    11781183      <p id="rfc.section.3.2.p.1">The representation data associated with an HTTP message is either provided as the payload body of the message or referred
    … …  
    32603265         code (e.g., combinations of request header fields and/or method(s)) along with any dependencies on response header fields
    32613266         (e.g., what fields are required and what fields can modify the semantics). A response that can transfer a payload ought to
    3262          specify expected cache behavior (e.g., cacheability and freshness criteria, as described in <a href="#Part6" id="rfc.xref.Part6.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) and whether the payload has any implied association with an identified resource (<a href="#identifying.payload" title="Identifying the Payload">Section&nbsp;3.1.4.1</a>).
     3267         specify expected cache behavior (e.g., cacheability and freshness criteria, as described in <a href="#Part6" id="rfc.xref.Part6.17"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) and whether the payload has any implied association with an identified resource (<a href="#identifying.payload" title="Identifying a Representation">Section&nbsp;3.1.4.1</a>).
    32633268      </p>
    32643269      <h3 id="rfc.section.9.2.3"><a href="#rfc.section.9.2.3">9.2.3</a>&nbsp;<a id="status.code.registration" href="#status.code.registration">Registrations</a></h3>

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

    r1924 r1925  
    285285   that reflects the current or desired state of a given resource, in a format
    286286   that can be readily communicated via the protocol, consisting of a set of
    287    metadata (representation header fields) and a potentially unbounded stream
    288    of octets (representation data).
     287   representation metadata and a potentially unbounded stream of
     288   representation data.
    289289</t>
    290290
    … …  
    698698<section title="Identification" anchor="identification">
    699699
    700 <section title="Identifying the Payload" anchor="identifying.payload">
     700<section title="Identifying a Representation" anchor="identifying.payload">
    701701<t>
    702702   When a complete or partial representation is transferred in a message
    703703   payload, it is often desirable for the sender to supply, or the recipient
    704    to determine, an identifier for the resource corresponding to that
     704   to determine, an identifier for a resource corresponding to that
    705705   representation.
    706706</t>
    … …  
    753753  <x:anchor-alias value="Content-Location"/>
    754754<t>
    755    The "Content-Location" header field supplies a URI that can be used
    756    as a specific identifier for the representation in this message.
     755   The "Content-Location" header field references a URI that can be used
     756   as a specific identifier for the representation in this message payload.
    757757   In other words, if one were to perform a GET on this URI at the time
    758758   of this message's generation, then a <x:ref>200 (OK)</x:ref> response would
    … …  
    771771</t>
    772772<t>
    773    If Content-Location is included in a response message and its value
    774    is the same as the effective request URI, then the response payload
    775    &SHOULD; be considered a current representation of that resource.
     773   If Content-Location is included in a <x:ref>2xx (Successful)</x:ref>
     774   response message and its value refers (after conversion to absolute form)
     775   to a URI that is the same as the effective request URI, then the response
     776   payload &SHOULD; be considered a current representation of that resource.
    776777   For a GET or HEAD request, this is the same as the default semantics
    777778   when no Content-Location is provided by the server.  For a state-changing
    … …  
    783784</t>
    784785<t>
    785    If Content-Location is included in a response message and its value
    786    differs from the effective request URI, then the origin server is
    787    informing recipients that this representation has its own, presumably
    788    more specific, identifier.  For a GET or HEAD request, this is an
    789    indication that the effective request URI identifies a resource that
    790    is subject to content negotiation and the selected representation for
    791    this response can also be found at the identified URI.  For other
    792    methods, such a Content-Location indicates that this representation
    793    contains a report on the action's status and the same report is
    794    available (for future access with GET) at the given URI.  For
    795    example, a purchase transaction made via a POST request might
    796    include a receipt document as the payload of the <x:ref>200 (OK)</x:ref>
    797    response; the Content-Location value provides an identifier for retrieving
    798    a copy of that same receipt in the future.
     786   If Content-Location is included in a <x:ref>2xx (Successful)</x:ref>
     787   response message and its field-value refers to a URI that differs from the
     788   effective request URI, then the origin server claims that the field-value
     789   is an identifier for the payload's representation. Such a claim can only be
     790   trusted if both identifiers share the same resource owner, which cannot be
     791   programmatically determined via HTTP.
     792   <list style="symbols">
     793    <t>For a response to a GET or HEAD request, this is an indication that the
     794       effective request URI identifies a resource that is subject to content
     795       negotiation and the Content-Location field-value is a more specific
     796       identifier for the selected representation.</t>
     797    <t>For a <x:ref>201 (Created)</x:ref> response to a state-changing method,
     798       a Content-Location field-value that is identical to the
     799       <x:ref>Location</x:ref> field-value indicates that this payload is a
     800       current representation of the newly created resource.</t>
     801    <t>Otherwise, such a Content-Location indicates that this payload is a
     802       representation reporting on the requested action's status and that the
     803       same report is available (for future access with GET) at the given URI.
     804       For example, a purchase transaction made via a POST request might
     805       include a receipt document as the payload of the <x:ref>200 (OK)</x:ref>
     806       response; the Content-Location field-value provides an identifier for
     807       retrieving a copy of that same receipt in the future.</t>
     808   </list>
    799809</t>
    800810<t>
    … …  
    827837   different from the URI used to retrieve it can be used to respond to
    828838   later requests on that Content-Location URI.
    829 </t>
    830 <t>
    831    If the Content-Location value is a partial URI, the partial URI is
    832    interpreted relative to the effective request URI.
    833839</t>
    834840</section>
Note: See TracChangeset for help on using the changeset viewer.