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.xml

    r2092 r2094  
    13081308  <iref primary="true" item="POST method" x:for-anchor=""/>
    13091309<t>
    1310    The POST method requests that the origin server accept the
    1311    representation enclosed in the request as data to be processed by the
    1312    <x:ref>target resource</x:ref>. For example, POST is frequently used for the following
    1313    functions (among others):
     1310   The POST method requests that the <x:ref>target resource</x:ref> process
     1311   the representation enclosed in the request according to the resource's own
     1312   specific semantics. For example, POST is used for the following functions
     1313   (among others):
    13141314  <list style="symbols">
    1315     <t>
    1316       Annotation of existing resources;
    1317     </t>
    1318     <t>
    1319         Posting a message to a bulletin board, newsgroup, mailing list,
    1320         or similar group of articles;
    1321     </t>
    1322     <t>
    1323         Providing a block of data, such as the result of submitting a
    1324         form, to a data-handling process;
    1325     </t>
    1326     <t>
    1327         Extending a database through an append operation.
    1328     </t>
     1315    <t>Providing a block of data, such as the fields entered into an HTML
     1316       form, to a data-handling process;</t>
     1317    <t>Posting a message to a bulletin board, newsgroup, mailing list, blog,
     1318       or similar group of articles;</t>
     1319    <t>Creating a new resource that has yet to be identified by the origin
     1320       server; and</t>
     1321    <t>Appending data to a resource's existing representation(s).</t>
    13291322  </list>
    13301323</t>
    13311324<t>
    1332    The actual function performed by the POST method is determined by the
    1333    origin server and is usually dependent on the effective request URI.
    1334 </t>
    1335 <t>
    1336    The action performed by the POST method might not result in a resource that
    1337    can be identified by a URI. In this case, either <x:ref>200 (OK)</x:ref> or
    1338    <x:ref>204 (No Content)</x:ref> is the appropriate response status
    1339    code, depending on whether or not the response includes a representation
    1340    that describes the result.
    1341 </t>
    1342 <t>
    1343    If one or more resources has been created on the origin server, the origin
    1344    server &SHOULD; send a <x:ref>201 (Created)</x:ref> response containing a
    1345    <x:ref>Location</x:ref> header field that provides an identifier for the
    1346    primary resource created (<xref target="header.location"/>) and a
    1347    representation that describes the status of the request and refers to the
    1348    new resource(s).
     1325   An origin server indicates response semantics by choosing an appropriate
     1326   status code depending on the result of processing the POST request;
     1327   almost all of the status codes defined by this specification might be
     1328   received in a response to POST (the exceptions being 206, 304, and 416).
     1329</t>
     1330<t>
     1331   If one or more resources has been created on the origin server as a result
     1332   of successfully processing a POST request, the origin server &SHOULD; send
     1333   a <x:ref>201 (Created)</x:ref> response containing a <x:ref>Location</x:ref>
     1334   header field that provides an identifier for the primary resource created
     1335   (<xref target="header.location"/>) and a representation that describes the
     1336   status of the request while referring to the new resource(s).
    13491337</t>
    13501338<t>
    13511339   Responses to POST requests are only cacheable when they include explicit
    1352    freshness information (see &p6-explicit;). A cache &MUST-NOT; use a cached
    1353    POST response to satisfy a subsequent GET or HEAD request unless the
    1354    response contains a <x:ref>Content-Location</x:ref> header field with the
    1355    same value as the POST's effective request URI (&header-content-location;).
    1356 </t>
    1357 <t>
    1358    Note that POST caching is not widely implemented.
    1359    However, the <x:ref>303 (See Other)</x:ref> response can be used to direct
    1360    the user agent to retrieve a cacheable representation of the resource.
     1340   freshness information (see &p6-explicit;). However, POST caching is not
     1341   widely implemented. For cases where an origin server wishes the client to
     1342   be able to cache the result of a POST in a way that can be reused by a
     1343   later GET, the origin server &MAY; send a <x:ref>200 (OK)</x:ref> response
     1344   containing the result and a <x:ref>Content-Location</x:ref> header field
     1345   that has the same value as the POST's effective request URI
     1346   (&header-content-location;).
     1347</t>
     1348<t>
     1349   If the result of processing a POST would be equivalent to a representation
     1350   of an existing resource, an origin server &MAY; redirect the user agent to
     1351   that resource by sending a <x:ref>303 (See Other)</x:ref> response with the
     1352   existing resource's identifier in the <x:ref>Location</x:ref> field.
     1353   This has the benefits of providing the user agent a resource identifier
     1354   and transferring the representation via a method more amenable to shared
     1355   caching, though at the cost of an extra request if the user agent does not
     1356   already have the representation cached.
    13611357</t>
    13621358</section>
Note: See TracChangeset for help on using the changeset viewer.