Ignore:
Timestamp:
19/07/10 11:52:07 (10 years ago)
Author:
fielding@…
Message:

Addresses #69: Clarify "Requested Variant"
Addresses #109: Clarify entity / representation / variant terminology

Replaced entity with payload and variant with representation.
Cleaned up description of 204 status code (related to ticket #22)
Rewrote section on Content-Location and refer to def in RFC2557.

Addresses #110: Clarify rules for determining what entities a response carries

Detail the rules for Content-Location and remove the cross-ref.

Addresses #167: Content-Location on 304 responses

Removed sentence in C-Loc that refers to using C-Loc to select a

variant from cache (an already removed "feature")

Addresses #136: confusing req. language for Content-Location

Removed the confusing paragraph because HTTP does not know
anything about variants behind the resource interface and
thus cannot make this an interop requirement. In any case,
it only existed to support the already removed cache feature
that nobody implemented.

Addresses #80: Content-Location isn't special

Clarifies that C-Loc is representation metadata and what
(not) to do with it if received on a request.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p3-payload.xml

    r854 r856  
    256256    <t>
    257257      The mechanism for selecting the appropriate representation when
    258       servicing a request. The representation of entities in any response
     258      servicing a request. The representation in any response
    259259      can be negotiated (including error responses).
    260260    </t>
    … …  
    262262</t>
    263263<t>
    264   <iref item="entity"/>
    265   <x:dfn>entity</x:dfn>
     264  <iref item="payload"/>
     265  <x:dfn>payload</x:dfn>
    266266  <list>
    267267    <t>
    268       The information transferred as the payload of a request or
    269       response. An entity consists of metadata in the form of
    270       entity-header fields and content in the form of an entity-body.
     268      The information transferred within a given message is called the
     269      payload, consisting  of optional payload metadata and an optional
     270      payload body.  The payload in HTTP is always a partial or complete
     271      representation of some resource, though which resource is represented
     272      is dependent on the type of message (request or response), the
     273      request method, and the response status code.
    271274    </t>
    272275  </list>
    … …  
    277280  <list>
    278281    <t>
    279       An entity included with a response that is subject to content
    280       negotiation. There may exist multiple
    281       representations associated with a particular response status.
    282     </t>
    283   </list>
    284 </t>
    285 <t>
    286   <iref item="variant"/>
    287   <x:dfn>variant</x:dfn>
    288   <list>
    289     <t>
    290       A resource may have one, or more than one, representation(s)
    291       associated with it at any given instant. Each of these
    292       representations is termed a "variant".  Use of the term "variant"
    293       does not necessarily imply that the resource is subject to content
    294       negotiation.
     282      A representation is information in a format that can be readily
     283      communicated from one party to another.  For our purposes, a
     284      representation is binary data and its associated metadata.
     285      A representation of a resource is information that reflects the
     286      state of that resource, as observed at some point in the past
     287      or to be desired at some point in the future.
    295288    </t>
    296289  </list>
    … …  
    14201413  <x:anchor-alias value="Content-Location-v"/>
    14211414<t>
    1422    The "Content-Location" entity-header field is used to supply a URI for the
    1423    entity in the message when it is accessible from a location separate from
    1424    the requested resource's URI.
    1425 </t>
    1426 <t>
    1427    A server &SHOULD; provide a Content-Location for the variant corresponding
    1428    to the response entity, especially in the case where a resource has multiple
    1429    entities associated with it, and those entities actually have separate
    1430    locations by which they might be individually accessed, the server &SHOULD;
    1431    provide a Content-Location for the particular variant which is returned.
     1415   The "Content-Location" header field supplies a URI that can be used
     1416   as a specific identifier for the representation in this message.
     1417   In other words, if one were to perform a GET on this URI at the time
     1418   of this message's generation, then a 200 response would contain the
     1419   same representation that is enclosed as payload in this message.
    14321420</t>
    14331421<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Content-Location"/><iref primary="true" item="Grammar" subitem="Content-Location-v"/>
    … …  
    14391427<t>
    14401428   The Content-Location value is not a replacement for the Effective
    1441    Request URI (&effective-request-uri;); it is only a statement of the location of the resource
    1442    corresponding to this particular entity at the time of the request.
    1443    Future requests &MAY; may be addressed to the Content-Location URI
    1444    if the desire is to identify the source of that particular
    1445    entity.
    1446 </t>
    1447 <t>
    1448    &response-representation; describes how clients may process the Content-Location header field.
    1449 </t>
    1450 <t>
    1451    A cache cannot assume that an entity with a Content-Location
     1429   Request URI (&effective-request-uri;).  It is representation metadata.
     1430   It has the same syntax and semantics as the header field of the same name
     1431   defined for MIME body parts in <xref target="RFC2557" x:sec="4"/>.
     1432   However, its appearance in an HTTP message has some special implications
     1433   for HTTP recipients.
     1434</t>
     1435<t>
     1436   If Content-Location is included in a response message and its value
     1437   is the same as the Effective Request URI, then the response payload
     1438   &SHOULD; be considered the current representation of that resource.
     1439   For a GET or HEAD request, this is the same as the default semantics
     1440   when no Content-Location is provided by the server.  For a state-changing
     1441   method like PUT or POST, it implies that the server's response contains
     1442   the new representation of that resource, thereby distinguishing it from
     1443   representations that might only report about the action (e.g., "It worked!").
     1444   This allows authoring applications to update their local copies without
     1445   the need for a subsequent GET request.
     1446</t>
     1447<t>
     1448   If Content-Location is included in a response message and its value
     1449   differs from the Effective Request URI, then the origin server is
     1450   informing recipients that this representation has its own, presumably
     1451   more specific, identifier.  For a GET or HEAD request, this is an
     1452   indication that the Effective Request URI identifies a resource that
     1453   is subject to content negotiation and the representation selected for
     1454   this response can also be found at the identified URI.  For other
     1455   methods, such a Content-Location indicates that this representation
     1456   contains a report on the action's status and the same report is
     1457   available (for future access with GET) at the given URI.  For
     1458   example, a purchase transaction made via the POST method may
     1459   include a receipt document as the payload of the 200 response;
     1460   the Content-Location value provides an identifier for retrieving
     1461   a copy of that same receipt in the future.
     1462</t>
     1463<t>
     1464   If Content-Location is included in a request message, then it &MAY;
     1465   be interpreted by the origin server as an indication of where the
     1466   user agent originally obtained the content of the enclosed
     1467   representation (prior to any subsequent modification of the content
     1468   by that user agent).  In other words, the user agent is providing
     1469   the same representation metadata that it received with the original
     1470   representation.  However, such interpretation &MUST-NOT; be used to
     1471   alter the semantics of the method requested by the client.  For
     1472   example, if a client makes a PUT request on a negotiated resource
     1473   and the origin server accepts that PUT (without redirection), then the
     1474   new set of values for that resource is expected to be consistent with
     1475   the one representation supplied in that PUT; the Content-Location
     1476   cannot be used as a form of reverse content selection that
     1477   identifies only one of the negotiated representations to be updated.
     1478   If the user agent had wanted the latter semantics, it would have applied
     1479   the PUT directly to the Content-Location URI.
     1480</t>
     1481<t>
     1482   A Content-Location field received in a request message is transitory
     1483   information that &SHOULD-NOT; be saved with other representation
     1484   metadata for use in later responses.  The Content-Location's value
     1485   might be saved for use in other contexts, such as within source links
     1486   or other metadata.
     1487</t>
     1488<t>
     1489   A cache cannot assume that a representation with a Content-Location
    14521490   different from the URI used to retrieve it can be used to respond to
    1453    later requests on that Content-Location URI. However, the Content-Location
    1454    can be used to differentiate between multiple entities
    1455    retrieved from a single requested resource, as described in &caching-neg-resp;.
    1456 </t>
    1457 <t>
    1458    If the Content-Location is a relative URI, the relative URI is
     1491   later requests on that Content-Location URI.
     1492</t>
     1493<t>
     1494   If the Content-Location value is a partial URI, it is
    14591495   interpreted relative to the Effective Request URI.
    1460 </t>
    1461 <t>
    1462    The meaning of the Content-Location header in requests is
    1463    undefined; servers are free to ignore it in those cases.
    14641496</t>
    14651497</section>
Note: See TracChangeset for help on using the changeset viewer.