Ignore:
Timestamp:
Jan 6, 2013, 11:07:55 PM (7 years ago)
Author:
fielding@…
Message:

(editorial) update description of POST

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p2-semantics.html

    r2092 r2094  
    14141414      <div id="rfc.iref.p.2"></div>
    14151415      <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>
    1416       <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
    1417          by the <a href="#resources" class="smpl">target resource</a>. For example, POST is frequently used for the following functions (among others):
     1416      <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
     1417         used for the following functions (among others):
    14181418      </p>
    14191419      <ul>
    1420          <li>Annotation of existing resources;</li>
    1421          <li>Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;</li>
    1422          <li>Providing a block of data, such as the result of submitting a form, to a data-handling process;</li>
    1423          <li>Extending a database through an append operation.</li>
     1420         <li>Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;</li>
     1421         <li>Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;</li>
     1422         <li>Creating a new resource that has yet to be identified by the origin server; and</li>
     1423         <li>Appending data to a resource's existing representation(s).</li>
    14241424      </ul>
    1425       <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
    1426          request URI.
    1427       </p>
    1428       <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
    1429          the result.
    1430       </p>
    1431       <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).
    1432       </p>
    1433       <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>).
    1434       </p>
    1435       <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.
     1425      <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
     1426         the POST request; almost all of the status codes defined by this specification might be received in a response to POST (the
     1427         exceptions being 206, 304, and 416).
     1428      </p>
     1429      <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
     1430         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).
     1431      </p>
     1432      <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
     1433         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>).
     1434      </p>
     1435      <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
     1436         more amenable to shared caching, though at the cost of an extra request if the user agent does not already have the representation
     1437         cached.
    14361438      </p>
    14371439      <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>
Note: See TracChangeset for help on using the changeset viewer.