Changeset 2094 for draft-ietf-httpbis/latest/p2-semantics.html

Timestamp:

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

Author:

fielding@…

Message:

(editorial) update description of POST

File:

• draft-ietf-httpbis/latest/p2-semantics.html (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>