Changeset 1876 for draft-ietf-httpbis/latest/p2-semantics.xml

Timestamp:

10/09/12 08:28:31 (9 years ago)

Author:

fielding@…

Message:

define representation correctly

File:

• draft-ietf-httpbis/latest/p2-semantics.xml (modified) (4 diffs)

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

@@ -106 +106 @@
   <!ENTITY deflate-coding             "<xref target='Part1' x:rel='#deflate.coding' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
   <!ENTITY gzip-coding                "<xref target='Part1' x:rel='#gzip.coding' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
-  <!ENTITY response-representation    "<xref target='identifying.response.associated.with.representation' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
 ]>
 <?rfc toc="yes" ?>
@@ -290 +289 @@
 <iref item="representation"/>
 <t>
-   A "<x:dfn>representation</x:dfn>" is information in a format that can be readily
-   communicated from one party to another.  A resource representation
-   is information that reflects the state of that resource, as observed
-   at some point in the past (e.g., in a response to GET) or to be
-   desired at some point in the future (e.g., in a PUT request).
-</t>
-<t>
-   Most, but not all, representations transferred via HTTP are intended
-   to be a representation of the target resource (the resource identified
-   by the effective request URI).  The precise semantics of a representation
-   are determined by the type of message (request or response), the request
-   method, the response status code, and the representation metadata. For
-   example, the above semantic is true for the representation in any
-   <x:ref>200 (OK)</x:ref> response to GET and for the representation in any PUT request.
-   A 200 response to PUT, in contrast, contains either a representation
-   that describes the successful action or a representation of the target
-   resource, with the latter indicated by a <x:ref>Content-Location</x:ref>
-   header field with the same value as the effective request URI.  Likewise,
-   response messages with an error status code usually contain a representation
-   that describes the error and what next steps are suggested for resolving it.
-</t>
-<t>
-   Request and Response messages &MAY; transfer a representation if not otherwise
-   restricted by the request method or response status code. A representation
-   consists of metadata (representation header fields) and data (representation
-   body).  When a complete or partial representation is enclosed in an HTTP message,
-   it is referred to as the payload of the message.
+   If we consider that a resource could be anything, and that the uniform
+   interface provided by HTTP is similar to a window through which one
+   can observe and act upon such a thing only through the communication of
+   messages to some independent actor on the other side, then we need an
+   abstraction to represent ("take the place of") the current or desired state
+   of that thing in our communications. We call that abstraction a
+   "<x:dfn>representation</x:dfn>" <xref target="REST"/>.
+</t>
+<t>
+   For the purposes of HTTP, a <x:dfn>representation</x:dfn> is information
+   that reflects the current or desired state of a given resource, in a format
+   that can be readily communicated via the protocol, consisting of a set of
+   metadata (representation header fields) and a potentially unbounded stream
+   of data (representation body).
+</t>
+<t>
+   HTTP messages can transfer a full or partial representation in the payload
+   (<xref target="payload"/>) if not otherwise restricted by the request
+   method or response status code. In a request, the purpose of such a
+   representation is defined by the method semantics. In a response, the
+   purpose is defined by both the request method and the response status code.
+</t>
+<t>
+   For example, a representation in the payload of a PUT request
+   (<xref target="PUT"/>) represents the desired state of the target resource
+   if the request is successfully applied, whereas a representation in the
+   payload of a POST request (<xref target="POST"/>) represents an anonymous
+   resource for providing data to be processed, such as a specific encoding
+   format for the information that a user entered within an HTML form.
+</t>
+<t>
+   Likewise, the payload of a <x:ref>200 (OK)</x:ref> response to GET
+   (<xref target="GET"/>) contains a representation of the target resource,
+   as observed at the time of the message origination date
+   (<xref target="header.date"/>), whereas the same response to POST might
+   contain either a representation of the processing result or a current
+   representation of the target resource after applying the processing.
+   Response messages with an error status code usually contain a
+   representation that describes the error and what next steps are suggested
+   for resolving it.
 </t>
 <t>
@@ -325 +337 @@
 </t>
 
-<section title="Identifying the Resource Associated with a Representation" anchor="identifying.response.associated.with.representation">
+<section title="Associating a Representation with its Resource" anchor="associating.representation.with.resource">
 <t>
    It is sometimes necessary to determine an identifier for the resource
@@ -4232 +4244 @@
    not allowed), and can define how to determine the resource which they
    carry a representation for (see <xref
-   target="identifying.response.associated.with.representation"/>; by default,
+   target="associating.representation.with.resource"/>; by default,
    it is anonymous).
 </t>