Changeset 856 for draft-ietf-httpbis


Ignore:
Timestamp:
Jul 19, 2010, 4:52:07 AM (9 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.

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

Legend:

Unmodified
Added
Removed

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

    r848 r856  
    11851185   The request has been fulfilled and has resulted in a new resource being
    11861186   created. The newly created resource can be referenced by the URI(s)
    1187    returned in the entity of the response, with the most specific URI
     1187   returned in the payload of the response, with the most specific URI
    11881188   for the resource given by a Location header field. The response
    1189    &SHOULD; include an entity containing a list of resource
     1189   &SHOULD; include a payload containing a list of resource
    11901190   characteristics and location(s) from which the user or user agent can
    1191    choose the one most appropriate. The entity format is specified by
     1191   choose the one most appropriate. The payload format is specified by
    11921192   the media type given in the Content-Type header field. The origin
    11931193   server &MUST; create the resource before returning the 201 status code.
    … …  
    11971197<t>
    11981198   A 201 response &MAY; contain an ETag response header field indicating
    1199    the current value of the entity tag for the requested variant just
    1200    created, see &header-etag;.
     1199   the current value of the entity tag for the representation of the resource
     1200   just created (see &header-etag;).
    12011201</t>
    12021202</section>
    … …  
    12431243  <iref primary="true" item="Status Codes" subitem="204 No Content" x:for-anchor=""/>
    12441244<t>
    1245    The server has fulfilled the request but does not need to return an
    1246    entity-body, and might want to return updated metainformation. The
    1247    response &MAY; include new or updated metainformation in the form of
    1248    entity-headers, which if present &SHOULD; be associated with the
    1249    requested variant.
    1250 </t>
    1251 <t>
    1252    If the client is a user agent, it &SHOULD-NOT;  change its document view
     1245   The server has successfully fulfilled the request, but there is no
     1246   additional content to return in the response payload body.  The
     1247   resource metadata and representation metadata in the response message's
     1248   header fields refer to the requested resource and its current
     1249   representation, respectively, after the requested action.
     1250   For example, if a 204 status is received in response to a PUT
     1251   and the response contains an Etag header field, then the value of
     1252   that field is the current entity-tag for the representation that
     1253   was successfully PUT to the requested resource.
     1254</t>
     1255<t>
     1256   If the client is a user agent, it &SHOULD-NOT; change its document view
    12531257   from that which caused the request to be sent. This response is
    12541258   primarily intended to allow input for actions to take place without
    12551259   causing a change to the user agent's active document view, although
    1256    any new or updated metainformation &SHOULD; be applied to the document
     1260   any new or updated metadata &SHOULD; be applied to the document
    12571261   currently in the user agent's active view.
    12581262</t>

  • 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.