Changeset 2094 for draft-ietf-httpbis/latest

Timestamp:

07/01/13 07:07:55 (10 years ago)

Author:

fielding@…

Message:

(editorial) update description of POST

Location:

draft-ietf-httpbis/latest

Files:

• p2-semantics.html (modified) (1 diff)
• p2-semantics.xml (modified) (1 diff)

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

@@ -1414 +1414 @@
       <div id="rfc.iref.p.2"></div>
       <h3 id="rfc.section.4.3.3"><a href="#rfc.section.4.3.3">4.3.3</a>&nbsp;<a id="POST" href="#POST">POST</a></h3>
-      <p id="rfc.section.4.3.3.p.1">The POST method requests that the origin server accept the representation enclosed in the request as data to be processed
-         by the <a href="#resources" class="smpl">target resource</a>. For example, POST is frequently used for the following functions (among others): 
+      <p id="rfc.section.4.3.3.p.1">The POST method requests that the <a href="#resources" class="smpl">target resource</a> process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is
+         used for the following functions (among others): 
       </p>
       <ul>
-         <li>Annotation of existing resources;</li>
-         <li>Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;</li>
-         <li>Providing a block of data, such as the result of submitting a form, to a data-handling process;</li>
-         <li>Extending a database through an append operation.</li>
+         <li>Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;</li>
+         <li>Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;</li>
+         <li>Creating a new resource that has yet to be identified by the origin server; and</li>
+         <li>Appending data to a resource's existing representation(s).</li>
       </ul>
-      <p id="rfc.section.4.3.3.p.2">The actual function performed by the POST method is determined by the origin server and is usually dependent on the effective
-         request URI.
-      </p>
-      <p id="rfc.section.4.3.3.p.3">The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either <a href="#status.200" class="smpl">200 (OK)</a> or <a href="#status.204" class="smpl">204 (No Content)</a> is the appropriate response status code, depending on whether or not the response includes a representation that describes
-         the result.
-      </p>
-      <p id="rfc.section.4.3.3.p.4">If one or more resources has been created on the origin server, the origin server <em class="bcp14">SHOULD</em> send a <a href="#status.201" class="smpl">201 (Created)</a> response containing a <a href="#header.location" class="smpl">Location</a> header field that provides an identifier for the primary resource created (<a href="#header.location" id="rfc.xref.header.location.1" title="Location">Section&nbsp;7.1.2</a>) and a representation that describes the status of the request and refers to the new resource(s).
-      </p>
-      <p id="rfc.section.4.3.3.p.5">Responses to POST requests are only cacheable when they include explicit freshness information (see <a href="p6-cache.html#calculating.freshness.lifetime" title="Calculating Freshness Lifetime">Section 4.1.1</a> of <a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). A cache <em class="bcp14">MUST NOT</em> use a cached POST response to satisfy a subsequent GET or HEAD request unless the response contains a <a href="#header.content-location" class="smpl">Content-Location</a> header field with the same value as the POST's effective request URI (<a href="#header.content-location" id="rfc.xref.header.content-location.2" title="Content-Location">Section&nbsp;3.1.4.2</a>).
-      </p>
-      <p id="rfc.section.4.3.3.p.6">Note that POST caching is not widely implemented. However, the <a href="#status.303" class="smpl">303 (See Other)</a> response can be used to direct the user agent to retrieve a cacheable representation of the resource.
+      <p id="rfc.section.4.3.3.p.2">An origin server indicates response semantics by choosing an appropriate status code depending on the result of processing
+         the POST request; almost all of the status codes defined by this specification might be received in a response to POST (the
+         exceptions being 206, 304, and 416).
+      </p>
+      <p id="rfc.section.4.3.3.p.3">If one or more resources has been created on the origin server as a result of successfully processing a POST request, the
+         origin server <em class="bcp14">SHOULD</em> send a <a href="#status.201" class="smpl">201 (Created)</a> response containing a <a href="#header.location" class="smpl">Location</a> header field that provides an identifier for the primary resource created (<a href="#header.location" id="rfc.xref.header.location.1" title="Location">Section&nbsp;7.1.2</a>) and a representation that describes the status of the request while referring to the new resource(s).
+      </p>
+      <p id="rfc.section.4.3.3.p.4">Responses to POST requests are only cacheable when they include explicit freshness information (see <a href="p6-cache.html#calculating.freshness.lifetime" title="Calculating Freshness Lifetime">Section 4.1.1</a> of <a href="#Part6" id="rfc.xref.Part6.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>). However, POST caching is not widely implemented. For cases where an origin server wishes the client to be able to cache
+         the result of a POST in a way that can be reused by a later GET, the origin server <em class="bcp14">MAY</em> send a <a href="#status.200" class="smpl">200 (OK)</a> response containing the result and a <a href="#header.content-location" class="smpl">Content-Location</a> header field that has the same value as the POST's effective request URI (<a href="#header.content-location" id="rfc.xref.header.content-location.2" title="Content-Location">Section&nbsp;3.1.4.2</a>).
+      </p>
+      <p id="rfc.section.4.3.3.p.5">If the result of processing a POST would be equivalent to a representation of an existing resource, an origin server <em class="bcp14">MAY</em> redirect the user agent to that resource by sending a <a href="#status.303" class="smpl">303 (See Other)</a> response with the existing resource's identifier in the <a href="#header.location" class="smpl">Location</a> field. This has the benefits of providing the user agent a resource identifier and transferring the representation via a method
+         more amenable to shared caching, though at the cost of an extra request if the user agent does not already have the representation
+         cached.
       </p>
       <h3 id="rfc.section.4.3.4"><a href="#rfc.section.4.3.4">4.3.4</a>&nbsp;<a id="PUT" href="#PUT">PUT</a></h3>

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

@@ -1308 +1308 @@
   <iref primary="true" item="POST method" x:for-anchor=""/>
 <t>
-   The POST method requests that the origin server accept the
-   representation enclosed in the request as data to be processed by the 
-   <x:ref>target resource</x:ref>. For example, POST is frequently used for the following
-   functions (among others):
+   The POST method requests that the <x:ref>target resource</x:ref> process
+   the representation enclosed in the request according to the resource's own
+   specific semantics. For example, POST is used for the following functions
+   (among others):
   <list style="symbols">
-    <t>
-      Annotation of existing resources;
-    </t>
-    <t>
-        Posting a message to a bulletin board, newsgroup, mailing list,
-        or similar group of articles;
-    </t>
-    <t>
-        Providing a block of data, such as the result of submitting a
-        form, to a data-handling process;
-    </t>
-    <t>
-        Extending a database through an append operation.
-    </t>
+    <t>Providing a block of data, such as the fields entered into an HTML
+       form, to a data-handling process;</t>
+    <t>Posting a message to a bulletin board, newsgroup, mailing list, blog,
+       or similar group of articles;</t>
+    <t>Creating a new resource that has yet to be identified by the origin
+       server; and</t>
+    <t>Appending data to a resource's existing representation(s).</t>
   </list>
 </t>
 <t>
-   The actual function performed by the POST method is determined by the
-   origin server and is usually dependent on the effective request URI.
-</t>
-<t>
-   The action performed by the POST method might not result in a resource that
-   can be identified by a URI. In this case, either <x:ref>200 (OK)</x:ref> or
-   <x:ref>204 (No Content)</x:ref> is the appropriate response status
-   code, depending on whether or not the response includes a representation
-   that describes the result.
-</t>
-<t>
-   If one or more resources has been created on the origin server, the origin
-   server &SHOULD; send a <x:ref>201 (Created)</x:ref> response containing a
-   <x:ref>Location</x:ref> header field that provides an identifier for the
-   primary resource created (<xref target="header.location"/>) and a
-   representation that describes the status of the request and refers to the
-   new resource(s).
+   An origin server indicates response semantics by choosing an appropriate
+   status code depending on the result of processing the POST request;
+   almost all of the status codes defined by this specification might be
+   received in a response to POST (the exceptions being 206, 304, and 416).
+</t>
+<t>
+   If one or more resources has been created on the origin server as a result
+   of successfully processing a POST request, the origin server &SHOULD; send
+   a <x:ref>201 (Created)</x:ref> response containing a <x:ref>Location</x:ref>
+   header field that provides an identifier for the primary resource created
+   (<xref target="header.location"/>) and a representation that describes the
+   status of the request while referring to the new resource(s).
 </t>
 <t>
    Responses to POST requests are only cacheable when they include explicit
-   freshness information (see &p6-explicit;). A cache &MUST-NOT; use a cached
-   POST response to satisfy a subsequent GET or HEAD request unless the
-   response contains a <x:ref>Content-Location</x:ref> header field with the
-   same value as the POST's effective request URI (&header-content-location;).
-</t>
-<t>
-   Note that POST caching is not widely implemented. 
-   However, the <x:ref>303 (See Other)</x:ref> response can be used to direct
-   the user agent to retrieve a cacheable representation of the resource.
+   freshness information (see &p6-explicit;). However, POST caching is not
+   widely implemented. For cases where an origin server wishes the client to
+   be able to cache the result of a POST in a way that can be reused by a
+   later GET, the origin server &MAY; send a <x:ref>200 (OK)</x:ref> response
+   containing the result and a <x:ref>Content-Location</x:ref> header field
+   that has the same value as the POST's effective request URI
+   (&header-content-location;).
+</t>
+<t>
+   If the result of processing a POST would be equivalent to a representation
+   of an existing resource, an origin server &MAY; redirect the user agent to
+   that resource by sending a <x:ref>303 (See Other)</x:ref> response with the
+   existing resource's identifier in the <x:ref>Location</x:ref> field.
+   This has the benefits of providing the user agent a resource identifier
+   and transferring the representation via a method more amenable to shared
+   caching, though at the cost of an extra request if the user agent does not
+   already have the representation cached.
 </t>
 </section>