rewritten section on Content-Location

As part of addressing tickets #109, #110, #167, #136, and #80
for draft 11, I rewrote much of the section on Content-Location
and added a long-requested description of how it can be used to
indicate the response payload is the same as a GET on the same URI.

========

5.7.  Content-Location

   The "Content-Location" header field supplies a URI that can be used
   as a specific identifier for the representation in this message.  In
   other words, if one were to perform a GET on this URI at the time of
   this message's generation, then a 200 response would contain the same
   representation that is enclosed as payload in this message.

     Content-Location   = "Content-Location" ":" OWS Content-Location-v
     Content-Location-v =  absolute-URI / partial-URI

   The Content-Location value is not a replacement for the Effective
   Request URI (Section 4.3 of [Part1]).  It is representation metadata.
   It has the same syntax and semantics as the header field of the same
   name defined for MIME body parts in Section 4 of [RFC2557].  However,
   its appearance in an HTTP message has some special implications for
   HTTP recipients.

   If Content-Location is included in a response message and its value
   is the same as the Effective Request URI, then the response payload
   SHOULD be considered the current representation of that resource.
   For a GET or HEAD request, this is the same as the default semantics
   when no Content-Location is provided by the server.  For a state-
   changing method like PUT or POST, it implies that the server's
   response contains the new representation of that resource, thereby
   distinguishing it from representations that might only report about
   the action (e.g., "It worked!").  This allows authoring applications
   to update their local copies without the need for a subsequent GET
   request.

   If Content-Location is included in a response message and its value
   differs from the Effective Request URI, then the origin server is
   informing recipients that this representation has its own, presumably
   more specific, identifier.  For a GET or HEAD request, this is an
   indication that the Effective Request URI identifies a resource that
   is subject to content negotiation and the representation selected for
   this response can also be found at the identified URI.  For other
   methods, such a Content-Location indicates that this representation
   contains a report on the action's status and the same report is
   available (for future access with GET) at the given URI.  For
   example, a purchase transaction made via the POST method might
   include a receipt document as the payload of the 200 response; the
   Content-Location value provides an identifier for retrieving a copy
   of that same receipt in the future.

   If Content-Location is included in a request message, then it MAY be
   interpreted by the origin server as an indication of where the user
   agent originally obtained the content of the enclosed representation
   (prior to any subsequent modification of the content by that user
   agent).  In other words, the user agent is providing the same
   representation metadata that it received with the original
   representation.  However, such interpretation MUST NOT be used to
   alter the semantics of the method requested by the client.  For
   example, if a client makes a PUT request on a negotiated resource and
   the origin server accepts that PUT (without redirection), then the
   new set of values for that resource is expected to be consistent with
   the one representation supplied in that PUT; the Content-Location
   cannot be used as a form of reverse content selection that identifies
   only one of the negotiated representations to be updated.  If the
   user agent had wanted the latter semantics, it would have applied the
   PUT directly to the Content-Location URI.

   A Content-Location field received in a request message is transitory
   information that SHOULD NOT be saved with other representation
   metadata for use in later responses.  The Content-Location's value
   might be saved for use in other contexts, such as within source links
   or other metadata.

   A cache cannot assume that a representation with a Content-Location
   different from the URI used to retrieve it can be used to respond to
   later requests on that Content-Location URI.

   If the Content-Location value is a partial URI, it is interpreted
   relative to the Effective Request URI.

========

Please let us know if you disagree with this change.

....Roy

Received on Wednesday, 28 July 2010 08:25:41 UTC