Ignore:
Timestamp:
17/12/12 07:14:12 (8 years ago)
Author:
fielding@…
Message:

editorial improvements to 1xx and 2xx status codes; partly addresses #419

File:
1 edited

Legend:

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

    r2054 r2055  
    17891789</t>
    17901790<t>
    1791    The only expectation defined by this specification is:
    1792 </t>
    1793 <t><iref primary="true" item="100-continue (expect value)"/><iref primary="true" item="Expect Values" subitem="100-continue"/>
    1794   100-continue
     1791   Comparison is case-insensitive for names (expect-name), and case-sensitive
     1792   for values (expect-value).
     1793</t>
     1794<t>
     1795   The Expect header field &MUST; be forwarded if the request is forwarded.
     1796</t>
     1797<t>
     1798   Many older HTTP/1.0 and HTTP/1.1 servers do not understand the Expect
     1799   header field.
     1800</t>
     1801
     1802<section title="Use of the 100 (Continue) Status" anchor="use.of.the.100.status">
     1803  <iref primary="true" item="100-continue (expect value)"/>
     1804  <iref primary="true" item="Expect Values" subitem="100-continue"/>
     1805  <x:anchor-alias value="100-continue"/>
     1806<t>
     1807   The only expectation defined by this specification is:
     1808</t>
     1809<t>
     1810  <x:dfn>100-continue</x:dfn>
    17951811   <list>
    17961812      <t>
    1797         The "100-continue" expectation is defined below. It does not support
    1798         any expect-params.
     1813        The request includes a payload body and the client will wait for a
     1814        <x:ref>100 (Continue)</x:ref> response after sending the request
     1815        header section but before sending the payload body.
     1816        The 100-continue expectation does not use any expect-params.
    17991817      </t>
    18001818   </list>
    18011819</t>
    18021820<t>
    1803    Comparison is case-insensitive for names (expect-name), and case-sensitive
    1804    for values (expect-value).
    1805 </t>
    1806 <t>
    1807    The Expect mechanism is hop-by-hop: the above requirements apply to any
    1808    server, including proxies. However, the Expect header field itself is
    1809    end-to-end; it &MUST; be forwarded if the request is forwarded.
    1810 </t>
    1811 <t>
    1812    Many older HTTP/1.0 and HTTP/1.1 applications do not understand the Expect
    1813    header field.
    1814 </t>
    1815 
    1816 <section title="Use of the 100 (Continue) Status" anchor="use.of.the.100.status">
    1817 <t>
    1818    The purpose of the <x:ref>100 (Continue)</x:ref> status code
     1821   The primary purpose of the <x:ref>100 (Continue)</x:ref> status code
    18191822   (<xref target='status.100'/>)
    18201823   is to allow a client that is sending a request message with a payload
     
    24692472</t>
    24702473<t>
    2471    HTTP status codes are extensible. HTTP applications are not required
     2474   HTTP status codes are extensible. HTTP clients are not required
    24722475   to understand the meaning of all registered status codes, though such
    2473    understanding is obviously desirable. However, applications &MUST;
     2476   understanding is obviously desirable. However, clients &MUST;
    24742477   understand the class of any status code, as indicated by the first
    2475    digit, and treat any unrecognized response as being equivalent to the
    2476    x00 status code of that class, with the exception that an
    2477    unrecognized response &MUST-NOT; be cached. For example, if an
    2478    unrecognized status code of 431 is received by the client, it can
    2479    safely assume that there was something wrong with its request and
    2480    treat the response as if it had received a 400 status code. In such
    2481    cases, user agents &SHOULD; present to the user the representation enclosed
    2482    with the response, since that representation is likely to include human-readable
    2483    information which will explain the unusual status.
     2478   digit, and treat an unrecognized status code as being equivalent to the
     2479   x00 status code of that class, with the exception that a response with an
     2480   unrecognized status code &MUST-NOT; be cached.
     2481</t>
     2482<t>
     2483   For example, if an unrecognized status code of 471 is received by a client,
     2484   the client can assume that there was something wrong with its request and
     2485   treat the response as if it had received a 400 status code. If the response
     2486   includes a message body, it will usually include a representation that
     2487   explains the response status.
    24842488</t>
    24852489<t>
     
    25102514  </list>
    25112515</t>
    2512 <t>
    2513    For most status codes the response can carry a payload, in which case a
    2514    <x:ref>Content-Type</x:ref> header field indicates the payload's media type
    2515    (&header-content-type;).
    2516 </t>
    25172516
    25182517<section title="Overview of Status Codes" anchor="overview.of.status.codes">
     
    26122611  <x:anchor-alias value="100 (Continue)"/>
    26132612<t>
    2614    The client &SHOULD; continue with its request. This interim response is
    2615    used to inform the client that the initial part of the request has
    2616    been received and has not yet been rejected by the server. The client
    2617    &SHOULD; continue by sending the remainder of the request or, if the
    2618    request has already been completed, ignore this response. The server
    2619    &MUST; send a final response after the request has been completed.
    2620    See <xref target="use.of.the.100.status"/> for detailed discussion of the
    2621    use and handling of this status code.
     2613   The <x:dfn>100 (Continue)</x:dfn> status code indicates that the initial
     2614   part of a request has been received and has not yet been rejected by the
     2615   server. The server intends to send a final response after the request has
     2616   been fully received and acted upon.
     2617</t>
     2618<t>
     2619   When the request contains an <x:ref>Expect</x:ref> header field that
     2620   includes a <x:ref>100-continue</x:ref> expectation, the 100 response
     2621   indicates that the server wishes to receive the request payload body,
     2622   as described in <xref target="use.of.the.100.status"/>.  The client
     2623   ought to continue sending the request and discard the 100 response.
     2624</t>
     2625<t>
     2626   If the request did not contain an <x:ref>Expect</x:ref> header field
     2627   containing the <x:ref>100-continue</x:ref> expectation,
     2628   the client can simply discard this interim response.
    26222629</t>
    26232630</section>
     
    26272634  <x:anchor-alias value="101 (Switching Protocols)"/>
    26282635<t>
    2629    The server understands and is willing to comply with the client's request,
    2630    via the <x:ref>Upgrade</x:ref> message header field (&header-upgrade;), for
     2636   The <x:dfn>101 (Switching Protocols)</x:dfn> status code indicates that the
     2637   server understands and is willing to comply with the client's request,
     2638   via the <x:ref>Upgrade</x:ref> header field (&header-upgrade;), for
    26312639   a change in the application protocol being used on this connection. The
    2632    server will switch protocols to those defined by the response's Upgrade
    2633    header field immediately after the empty line which terminates the 101
    2634    response.
    2635 </t>
    2636 <t>
    2637    The protocol &SHOULD; be switched only when it is advantageous to do
    2638    so. For example, switching to a newer version of HTTP is advantageous
    2639    over older versions, and switching to a real-time, synchronous
    2640    protocol might be advantageous when delivering resources that use
    2641    such features.
     2640   server will switch to the protocol(s) indicated within the response's
     2641   Upgrade header field immediately after the empty line which terminates the
     2642   101 response.
     2643</t>
     2644<t>
     2645   It is assumed that the server will only agree to switch protocols when
     2646   it is advantageous to do so. For example, switching to a newer version of
     2647   HTTP might be advantageous over older versions, and switching to a
     2648   real-time, synchronous protocol might be advantageous when delivering
     2649   resources that use such features.
    26422650</t>
    26432651</section>
     
    26582666  <x:anchor-alias value="200 (OK)"/>
    26592667<t>
    2660    The request has succeeded. The payload sent in the response
     2668   The <x:dfn>200 (OK)</x:dfn> status code indicates that the request has
     2669   succeeded. The payload sent in the response
    26612670   is dependent on the method used in the request, for example:
    26622671  <list style="hanging">
     
    26862695  <x:anchor-alias value="201 (Created)"/>
    26872696<t>
    2688    The request has been fulfilled and has resulted in one or more new resources
    2689    being created.
     2697   The <x:dfn>201 (Created)</x:dfn> status code indicates that the request has
     2698   been fulfilled and has resulted in one or more new resources being created.
    26902699</t>
    26912700<t>
     
    26932702   with the most relevant URI also being carried in the <x:ref>Location</x:ref>
    26942703   header field. If the newly created resource's URI is the same as the
    2695    Effective Request URI, this information can be omitted (e.g., in the case of
    2696    a response to a PUT request). 
    2697 </t>
    2698 <t>
    2699    The origin server &MUST; create the resource(s) before sending the 201 status
    2700    code. If the action cannot be carried out immediately, the server &SHOULD;
    2701    respond with a <x:ref>202 (Accepted)</x:ref> response instead.
    2702 </t>
    2703 <t>
    2704    A 201 response &MAY; contain an <x:ref>ETag</x:ref> response header field
    2705    indicating the current value of the entity-tag for the representation of the
    2706    resource identified by the <x:ref>Location</x:ref> header field or, in case
    2707    the Location header field was omitted, by the Effective Request URI (see
    2708    &header-etag;).
     2704   effective request URI, the Location field can be omitted.
     2705</t>
     2706<t>
     2707   If an <x:ref>ETag</x:ref> header field is present in a 201 response, its
     2708   field value is the entity-tag for the representation created, which
     2709   is the new representation of the resource identified by either the
     2710   <x:ref>Location</x:ref> header field or, if no Location header field
     2711   is received, by the effective request URI (see &header-etag;).
    27092712</t>
    27102713</section>
     
    27142717  <x:anchor-alias value="202 (Accepted)"/>
    27152718<t>
    2716    The request has been accepted for processing, but the processing has
    2717    not been completed.  The request might or might not eventually be
    2718    acted upon, as it might be disallowed when processing actually takes
    2719    place. There is no facility for re-sending a status code from an
    2720    asynchronous operation such as this.
     2719   The <x:dfn>202 (Accepted)</x:dfn> status code indicates that the request
     2720   has been accepted for processing, but the processing has not been
     2721   completed. The request might or might not eventually be acted upon, as it
     2722   might be disallowed when processing actually takes place. There is no
     2723   facility for re-sending a status code from an asynchronous operation such
     2724   as this.
    27212725</t>
    27222726<t>
     
    27262730   requiring that the user agent's connection to the server persist
    27272731   until the process is completed. The representation sent with this
    2728    response &SHOULD; include an indication of the request's current status
     2732   response ought to describe the request's current status
    27292733   and either a pointer to a status monitor or some estimate of when the
    27302734   user can expect the request to be fulfilled.
     
    27362740  <x:anchor-alias value="203 (Non-Authoritative Information)"/>
    27372741<t>
    2738    The request was successful but the enclosed payload has been modified
    2739    from that of the origin server's <x:ref>200 (OK)</x:ref> response by a
    2740    transforming proxy (&transformations;). This status code allows the proxy
    2741    to notify recipients when a transformation has been applied, since that
    2742    knowledge might impact later decisions regarding the content.
    2743    For example, future cache validation requests for the content might only
    2744    be applicable along the same request path (through the same proxies).
     2742   The <x:dfn>203 (Non-Authoritative Information)</x:dfn> status code
     2743   indicates that the request was successful but the enclosed payload has been
     2744   modified from that of the origin server's <x:ref>200 (OK)</x:ref> response
     2745   by a transforming proxy (&transformations;). This status code allows the
     2746   proxy to notify recipients when a transformation has been applied, since
     2747   that knowledge might impact later decisions regarding the content. For
     2748   example, future cache validation requests for the content might only be
     2749   applicable along the same request path (through the same proxies).
    27452750</t>
    27462751<t>
     
    27552760  <x:anchor-alias value="204 (No Content)"/>
    27562761<t>
    2757    The 204 (No Content) status code indicates that the server has
    2758    successfully fulfilled the request and that there is no additional
    2759    content to send in the response payload body.  Metadata in the
    2760    response header fields refer to the target resource and its current
    2761    representation after the requested action.
     2762   The <x:dfn>204 (No Content)</x:dfn> status code indicates that the server
     2763   has successfully fulfilled the request and that there is no additional
     2764   content to send in the response payload body. Metadata in the response
     2765   header fields refer to the target resource and its current representation
     2766   after the requested action.
    27622767</t>
    27632768<t>
     
    27692774<t>
    27702775   The 204 response allows a server to indicate that the action has been
    2771    successfully applied to the target resource while implying that the
    2772    user agent &SHOULD-NOT; traverse away from its current "document view"
     2776   successfully applied to the target resource, while implying that the
     2777   user agent does not need to traverse away from its current "document view"
    27732778   (if any).  The server assumes that the user agent will provide some
    27742779   indication of the success to its user, in accord with its own interface,
     
    27842789</t>
    27852790<t>
    2786    The 204 response &MUST-NOT; include a message body, and thus is always
     2791   A 204 response does not include a message body, and thus is always
    27872792   terminated by the first empty line after the header fields.
    27882793</t>
     
    27922797  <iref primary="true" item="205 Reset Content (status code)" x:for-anchor=""/>
    27932798<t>
    2794    The server has fulfilled the request and the user agent &SHOULD; reset
    2795    the document view which caused the request to be sent. This response
    2796    is primarily intended to allow input for actions to take place via
    2797    user input, followed by a clearing of the form in which the input is
    2798    given so that the user can easily initiate another input action.
     2799   The <x:dfn>205 (Reset Content)</x:dfn> status code indicates that the
     2800   server has fulfilled the request and desires that the user agent reset the
     2801   "document view", which caused the request to be sent, to its original state
     2802   as received from the origin server.
    27992803</t>
    28002804<t>   
    2801    The message body included with the response &MUST; be empty. Note that
    2802    receivers still need to parse the response according to the algorithm defined
    2803    in &message-body;.
     2805   This response is intended to support a common data entry use case where
     2806   the user receives content that supports data entry (a form, notepad,
     2807   canvas, etc.), enters or manipulates data in that space, causes the entered
     2808   data to be submitted in a request, and then the data entry mechanism is
     2809   reset for the next entry so that the user can easily initiate another
     2810   input action.
     2811</t>
     2812<t>
     2813   Since the 205 status code implies that no additional content will be
     2814   provided in the payload, the server &MUST; send a message body of zero
     2815   length. In other words, the server &MUST; send a "Content-Length: 0" field
     2816   in a 205 response or close the connection immediately after sending the
     2817   blank line terminating the header section.
    28042818</t>
    28052819</section>
Note: See TracChangeset for help on using the changeset viewer.