Ignore:
Timestamp:
16/12/12 03:46:23 (8 years ago)
Author:
fielding@…
Message:

editorial fixes in methods; use send instead of return, sent instead of returned; partly addresses #419

File:
1 edited

Legend:

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

    r2051 r2052  
    10461046   it indicates the purpose for which the client has made this request
    10471047   and what is expected by the client as a successful result.  The request
    1048    semantics &MAY; be further specialized by the semantics of some header
     1048   semantics might be further specialized by the semantics of some header
    10491049   fields when present in a request (<xref target="request.header.fields"/>)
    10501050   if those additional semantics do not conflict with the method.
     
    10651065   not resource-specific, since uniform interfaces provide for better
    10661066   visibility and reuse in network-based systems <xref target="REST"/>.
    1067    Once defined, a standardized method &MUST; have the same semantics when
     1067   Once defined, a standardized method ought to have the same semantics when
    10681068   applied to any resource, though each resource determines for itself
    10691069   whether those semantics are implemented or allowed.
     
    11051105</texttable>
    11061106<t>
    1107    The methods GET and HEAD &MUST; be supported by all general-purpose
    1108    servers. All other methods are &OPTIONAL;.
    1109    When implemented, a server &MUST; implement the above methods according
    1110    to the semantics defined for them in <xref target="method.definitions"/>.
    1111 </t>
    1112 <t>
    1113    Additional methods &MAY; be used in HTTP; many have already been
    1114    standardized outside the scope of this specification and ought to be
    1115    registered within the HTTP Method Registry maintained by IANA, as defined
    1116    in <xref target="method.registry"/>.
     1107   All general-purpose servers &MUST; support the methods GET and HEAD.
     1108   All other methods are &OPTIONAL;; when implemented, a server &MUST;
     1109   implement the above methods according to the semantics defined for them
     1110   in <xref target="method.definitions"/>.
     1111</t>
     1112<t>
     1113   Additional methods, outside the scope of this specification, have been
     1114   standardized for use in HTTP.  All such methods ought to be registered
     1115   within the HTTP Method Registry maintained by IANA, as defined in
     1116   <xref target="method.registry"/>.
    11171117</t>
    11181118<t>
     
    11551155</t>
    11561156<t>
    1157    The GET, HEAD, OPTIONS, and TRACE request methods are defined to be safe.
     1157   Of the request methods defined by this specification, the
     1158   GET, HEAD, OPTIONS, and TRACE methods are defined to be safe.
    11581159</t>
    11591160<t>
     
    11921193   "<x:dfn anchor="idempotent">idempotent</x:dfn>" if the intended effect
    11931194   of multiple identical requests is the same as for a single request.
    1194    PUT, DELETE, and all safe request methods are idempotent.
     1195   Of the request methods defined by this specification, the
     1196   PUT, DELETE, and safe request methods are idempotent.
    11951197</t>
    11961198<t>
     
    12401242</t>
    12411243<t>   
    1242    If the target resource is a data-producing process, it is the
    1243    produced data which shall be returned as the representation in the response and not
    1244    the source text of the process, unless that text happens to be the output of
    1245    the process.
     1244   If the target resource is a data-producing process, the produced data will
     1245   be sent as the representation, not the source text of the process,
     1246   unless that text happens to be the output of the process.
    12461247</t>
    12471248<t>
     
    12871288<t>
    12881289   The HEAD method is identical to GET except that the server &MUST-NOT;
    1289    return a message body in the response. The metadata contained
     1290   send a message body in the response. The metadata contained
    12901291   in the HTTP header fields in response to a HEAD request &SHOULD; be identical
    12911292   to the information sent in response to a GET request. This method can
     
    13121313   The POST method requests that the origin server accept the
    13131314   representation enclosed in the request as data to be processed by the
    1314    target resource. POST is designed to allow a uniform method to cover the
    1315    following functions:
     1315   target resource. For example, POST is frequently used for the following
     1316   functions (among others):
    13161317  <list style="symbols">
    13171318    <t>
     
    13331334<t>
    13341335   The actual function performed by the POST method is determined by the
    1335    server and is usually dependent on the effective request URI.
     1336   origin server and is usually dependent on the effective request URI.
    13361337</t>
    13371338<t>
     
    13431344</t>
    13441345<t>
    1345    If a resource has been created on the origin server, the response
    1346    &SHOULD; be <x:ref>201 (Created)</x:ref> and contain a representation which
    1347    describes the status of the request and refers to the new resource, and a
    1348    <x:ref>Location</x:ref> header field (see <xref target="header.location"/>).
     1346   If one or more resources has been created on the origin server, the response
     1347   &SHOULD; be <x:ref>201 (Created)</x:ref>, contain a representation which
     1348   describes the status of the request and refers to the new resource(s), and
     1349   include a <x:ref>Location</x:ref> header field that provides an identifier
     1350   for the primary resource created (see <xref target="header.location"/>).
    13491351</t>
    13501352<t>
     
    13721374   enclosed in the request message payload.  A successful PUT of a given
    13731375   representation would suggest that a subsequent GET on that same target
    1374    resource will result in an equivalent representation being returned in
     1376   resource will result in an equivalent representation being sent in
    13751377   a <x:ref>200 (OK)</x:ref> response.  However, there is no guarantee that
    13761378   such a state change will be observable, since the target resource might be
     
    13901392</t>
    13911393<t>
    1392    Unrecognized header fields &SHOULD; be ignored (i.e., not saved
    1393    as part of the resource state).
     1394   An origin server &SHOULD; ignore unrecognized header fields received in a
     1395   PUT request (i.e., do not save them as part of the resource state).
    13941396</t>
    13951397<t>
     
    14951497  <iref primary="true" item="DELETE method" x:for-anchor=""/>
    14961498<t>
    1497    The DELETE method requests that the origin server delete the target
    1498    resource. This method &MAY; be overridden by
    1499    human intervention (or other means) on the origin server. The client cannot
    1500    be guaranteed that the operation has been carried out, even if the
    1501    status code returned from the origin server indicates that the action
    1502    has been completed successfully. However, the server &SHOULD-NOT;
    1503    indicate success unless, at the time the response is given, it
    1504    intends to delete the resource or move it to an inaccessible
    1505    location.
    1506 </t>
    1507 <t>
    1508    A successful response &SHOULD; be <x:ref>200 (OK)</x:ref> if the response
    1509    includes a representation describing the status, <x:ref>202 (Accepted)</x:ref>
    1510    if the action has not yet been enacted, or <x:ref>204 (No Content)</x:ref> if
    1511    the action has been enacted but the response does not include a representation.
     1499   The DELETE method requests that the origin server remove the association
     1500   between the target resource and its current representations or
     1501   implementation. In effect, this method is similar to the rm command in
     1502   UNIX: it expresses a deletion operation on the URI mapping of the
     1503   origin server, rather than an expectation that the information be deleted.
     1504   The representations might or might not be destroyed by the origin server,
     1505   and the associated storage might or might not be reclaimed, depending
     1506   entirely on the nature of the resource and its implementation by the
     1507   origin server (which are beyond the scope of this specification).
     1508</t>
     1509<t>
     1510   Relatively few resources allow the DELETE method &mdash; its primary use
     1511   is for remote authoring environments, where the user has some direction
     1512   regarding its effect. For example, a resource that was previously created
     1513   using a PUT request, or identified via the Location header field after a
     1514   <x:ref>201 (Created)</x:ref> response to a POST request, might allow a
     1515   corresponding DELETE request to undo those actions.  Similarly, custom
     1516   user agent implementations that implement an authoring function, such as
     1517   revision control clients using HTTP for remote operations, might use
     1518   DELETE based on an assumption that the server's URI space has been crafted
     1519   to correspond to a version repository.
     1520</t>
     1521<t>
     1522   If a DELETE method is successfully applied, the origin server &SHOULD; send
     1523   a <x:ref>202 (Accepted)</x:ref> status code if the action seems okay but
     1524   has not yet been enacted, or
     1525   a <x:ref>204 (No Content)</x:ref> status code if the action has been
     1526   enacted and no further information is to be supplied, or
     1527   a <x:ref>200 (OK)</x:ref> status code if the action has been enacted and
     1528   the response message includes a representation describing the status.
    15121529</t>
    15131530<t>
     
    15271544  <iref primary="true" item="CONNECT method" x:for-anchor=""/>
    15281545<t>
    1529    The CONNECT method requests that the proxy establish a tunnel
    1530    to the request-target and, if successful, thereafter restrict its behavior
    1531    to blind forwarding of packets until the connection is closed.
    1532 </t>
    1533 <t>
    1534    When using CONNECT, the request-target &MUST; use the authority form
    1535    (&request-target;); i.e., the request-target consists of only the
    1536    host name and port number of the tunnel destination, separated by a colon.
    1537    For example,
     1546   The CONNECT method is only applicable as a request to a proxy.
     1547   A CONNECT requests that the recipient establish a tunnel to the destination
     1548   origin server identified by the request-target and, if successful,
     1549   thereafter restrict its behavior to blind forwarding of packets, in
     1550   both directions, until the connection is closed.
     1551</t>
     1552<t>
     1553   A client sending a CONNECT request &MUST; send the authority form of
     1554   request-target (&request-target;); i.e., the request-target consists
     1555   of only the host name and port number of the tunnel destination, separated
     1556   by a colon. For example,
    15381557</t>
    15391558<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
     
    15431562</artwork></figure>
    15441563<t>
    1545    Any <x:ref>2xx (Successful)</x:ref> response to a CONNECT request indicates that the
    1546    proxy has established a connection to the requested host and port,
    1547    and has switched to tunneling the current connection to that server
    1548    connection.
    1549    The tunneled data from the server begins immediately after the blank line
    1550    that concludes the successful response's header block.
     1564   The recipient proxy can establish a tunnel either by directly connecting to
     1565   the request-target or, if configured to use another proxy, by forwarding
     1566   the CONNECT request to the next inbound proxy.
     1567   Any <x:ref>2xx (Successful)</x:ref> response to a CONNECT request indicates
     1568   that the sender (and any inbound proxies) will switch to tunnel mode
     1569   immediately after the blank line that concludes the successful response's
     1570   header block; data received after that blank line is from the server
     1571   identified by the request-target.
    15511572</t>
    15521573<t>
     
    15621583<t>
    15631584   Proxy authentication might be used to establish the
    1564    authority to create a tunnel:
     1585   authority to create a tunnel.  For example,
    15651586</t>
    15661587<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
     
    15761597</t>
    15771598<t>
    1578    Similar to a pipelined HTTP/1.1 request, data to be tunneled from client
    1579    to server &MAY; be sent immediately after the request (before a response
    1580    is received). The usual caveats also apply:
    1581    data can be discarded if the eventual response is negative, and the
    1582    connection can be reset with no response if more than one TCP segment
    1583    is outstanding.
    1584 </t>
    1585 <t>
    1586    It might be the case that the proxy itself can only reach the requested
    1587    origin server through another proxy.  In this case, the first proxy
    1588    &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel
    1589    to the authority.  A proxy &MUST-NOT; respond with any <x:ref>2xx</x:ref> status code
    1590    unless it has either a direct or tunnel connection established to the
    1591    authority.
    1592 </t>
    1593 <t>
    1594    If at any point either one of the peers gets disconnected, any
    1595    outstanding data that came from that peer will be passed to the other
    1596    one, and after that also the other connection will be terminated by
    1597    the proxy. If there is outstanding data to that peer undelivered,
     1599   When a tunnel intermediary detects that either side has closed its
     1600   connection, any outstanding data that came from that side will first be
     1601   sent to the other side and then the intermediary will close both
     1602   connections. If there is outstanding data left undelivered,
    15981603   that data will be discarded.
    15991604</t>
    16001605<t>
    16011606   An origin server which receives a CONNECT request for itself &MAY;
    1602    respond with a <x:ref>2xx</x:ref> status code to indicate that a connection is
    1603    established.  However, most origin servers do not implement CONNECT.
     1607   respond with a <x:ref>2xx</x:ref> status code to indicate that a connection
     1608   is established.  However, most origin servers do not implement CONNECT.
    16041609</t>
    16051610</section>
     
    18491854    <t> Upon receiving a request which includes an <x:ref>Expect</x:ref> header
    18501855        field with the "100-continue" expectation, an origin server &MUST;
    1851         either respond with <x:ref>100 (Continue)</x:ref> status code and continue to read
    1852         from the input stream, or respond with a final status code. The
    1853         origin server &MUST-NOT; wait for the payload body before sending
    1854         the <x:ref>100 (Continue)</x:ref> response. If it responds with a final status
    1855         code, it &MAY; close the transport connection or it &MAY; continue
    1856         to read and discard the rest of the request.  It &MUST-NOT;
    1857         perform the request method if it returns a final status code.
     1856        either respond with <x:ref>100 (Continue)</x:ref> status code and
     1857        continue to read from the input stream, or respond with a final status
     1858        code. The origin server &MUST-NOT; wait for the payload body before
     1859        sending the <x:ref>100 (Continue)</x:ref> response. If the origin
     1860        server responds with a final status code, it &MUST-NOT; have performed
     1861        the request method and &MAY; either close the connection or continue
     1862        to read and discard the rest of the request.
    18581863    </t>
    1859     <t> An origin server &SHOULD-NOT;  send a <x:ref>100 (Continue)</x:ref> response if
    1860         the request message does not include an <x:ref>Expect</x:ref> header
    1861         field with the "100-continue" expectation, and &MUST-NOT; send a
    1862         <x:ref>100 (Continue)</x:ref> response if such a request comes from an HTTP/1.0
    1863         (or earlier) client. There is an exception to this rule: for
    1864         compatibility with <xref target="RFC2068"/>, a server &MAY; send a <x:ref>100 (Continue)</x:ref>
    1865         status code in response to an HTTP/1.1 PUT or POST request that does
    1866         not include an Expect header field with the "100-continue"
    1867         expectation. This exception, the purpose of which is
    1868         to minimize any client processing delays associated with an
    1869         undeclared wait for <x:ref>100 (Continue)</x:ref> status code, applies only to
    1870         HTTP/1.1 requests, and not to requests with any other HTTP-version
    1871         value.
     1864    <t> An origin server &SHOULD-NOT; send a <x:ref>100 (Continue)</x:ref>
     1865        response if the request message does not include an
     1866        <x:ref>Expect</x:ref> header field with the "100-continue"
     1867        expectation, and &MUST-NOT; send a <x:ref>100 (Continue)</x:ref>
     1868        response if such a request comes from an HTTP/1.0 (or earlier) client.
     1869        There is an exception to this rule: for compatibility with
     1870        <xref target="RFC2068"/>, a server &MAY; send a
     1871        <x:ref>100 (Continue)</x:ref> status code in response to an HTTP/1.1
     1872        PUT or POST request that does not include an Expect header field with
     1873        the "100-continue" expectation. This exception, the purpose of which
     1874        is to minimize any client processing delays associated with an
     1875        undeclared wait for <x:ref>100 (Continue)</x:ref> status code, applies
     1876        only to HTTP/1.1 requests, and not to requests with any other
     1877        HTTP-version value.
    18721878    </t>
    1873     <t> An origin server &MAY; omit a <x:ref>100 (Continue)</x:ref> response if it has
    1874         already received some or all of the payload body for the
     1879    <t> An origin server &MAY; omit a <x:ref>100 (Continue)</x:ref> response
     1880        if it has already received some or all of the payload body for the
    18751881        corresponding request.
    18761882    </t>
    1877     <t> An origin server that sends a <x:ref>100 (Continue)</x:ref> response &MUST;
    1878         ultimately send a final status code, once the payload body is
    1879         received and processed, unless it terminates the transport
    1880         connection prematurely.
     1883    <t> An origin server that sends a <x:ref>100 (Continue)</x:ref> response
     1884        &MUST; ultimately send a final status code, once the payload body is
     1885        received and processed, unless it terminates the transport connection
     1886        prematurely.
    18811887    </t>
    18821888    <t> If an origin server receives a request that does not include an
     
    26582664  <x:anchor-alias value="200 (OK)"/>
    26592665<t>
    2660    The request has succeeded. The payload returned with the response
     2666   The request has succeeded. The payload sent in the response
    26612667   is dependent on the method used in the request, for example:
    26622668  <list style="hanging">
     
    26972703</t>
    26982704<t>
    2699    The origin server &MUST; create the resource(s) before returning the 201 status
     2705   The origin server &MUST; create the resource(s) before sending the 201 status
    27002706   code. If the action cannot be carried out immediately, the server &SHOULD;
    27012707   respond with a <x:ref>202 (Accepted)</x:ref> response instead.
     
    27252731   batch-oriented process that is only run once per day) without
    27262732   requiring that the user agent's connection to the server persist
    2727    until the process is completed. The representation returned with this
     2733   until the process is completed. The representation sent with this
    27282734   response &SHOULD; include an indication of the request's current status
    27292735   and either a pointer to a status monitor or some estimate of when the
     
    27572763   The 204 (No Content) status code indicates that the server has
    27582764   successfully fulfilled the request and that there is no additional
    2759    content to return in the response payload body.  Metadata in the
     2765   content to send in the response payload body.  Metadata in the
    27602766   response header fields refer to the target resource and its current
    27612767   representation after the requested action.
     
    29292935<t>
    29302936   The target resource has been assigned a new permanent URI and any
    2931    future references to this resource &SHOULD; use one of the returned
     2937   future references to this resource &SHOULD; use one of the enclosed
    29322938   URIs.  Clients with link editing capabilities ought to automatically
    29332939   re-link references to the effective request URI to one or more of the new
    2934    references returned by the server, where possible.
     2940   references sent by the server, where possible.
    29352941</t>
    29362942<t>
     
    31553161<x:note>
    31563162  <t>
    3157     &Note; HTTP/1.1 servers are allowed to return responses which are
     3163    &Note; HTTP/1.1 servers are allowed to send responses which are
    31583164    not acceptable according to the accept header fields sent in the
    31593165    request. In some cases, this might even be preferable to sending a
     
    34053411  <t>
    34063412    <x:h>Note</x:h> to implementers: some deployed proxies are known to
    3407     return <x:ref>400 (Bad Request)</x:ref> or <x:ref>500 (Internal Server
     3413    send <x:ref>400 (Bad Request)</x:ref> or <x:ref>500 (Internal Server
    34083414    Error)</x:ref> when DNS lookups time out.
    34093415  </t>
Note: See TracChangeset for help on using the changeset viewer.