Ignore:
Timestamp:
06/01/13 07:26:25 (10 years ago)
Author:
fielding@…
Message:

(editorial) more consistency regarding representation; explain what HEAD does instead of what it doesn't do

Location:
draft-ietf-httpbis/latest
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p2-semantics.html

    r2090 r2091  
    11441144</pre><div id="rfc.iref.p.1"></div>
    11451145      <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a>&nbsp;<a id="payload" href="#payload">Payload Semantics</a></h2>
    1146       <p id="rfc.section.3.3.p.1">Some HTTP messages transfer a complete or partial representation as the message "<dfn>payload</dfn>". In some cases, a payload might only contain the associated representation's header fields (e.g., responses to HEAD) or
     1146      <p id="rfc.section.3.3.p.1">Some HTTP messages transfer a complete or partial representation as the message "<dfn>payload</dfn>". In some cases, a payload might contain only the associated representation's header fields (e.g., responses to HEAD) or
    11471147         only some part(s) of the representation data (e.g., the <a href="p5-range.html#status.206" class="smpl">206 (Partial Content)</a> status code).
    11481148      </p>
    1149       <p id="rfc.section.3.3.p.2">The purpose of a payload in a request is defined by the method semantics. In a response, the payload's purpose is defined
    1150          by both the request method and the response status code.
    1151       </p>
    1152       <p id="rfc.section.3.3.p.3">For example, a representation in the payload of a PUT request (<a href="#PUT" id="rfc.xref.PUT.1" title="PUT">Section&nbsp;4.3.4</a>) represents the desired state of the <a href="#resources" class="smpl">target resource</a> if the request is successfully applied, whereas a representation in the payload of a POST request (<a href="#POST" id="rfc.xref.POST.1" title="POST">Section&nbsp;4.3.3</a>) represents an anonymous resource for providing data to be processed, such as the information that a user entered within
     1149      <p id="rfc.section.3.3.p.2">The purpose of a payload in a request is defined by the method semantics. For example, a representation in the payload of
     1150         a PUT request (<a href="#PUT" id="rfc.xref.PUT.1" title="PUT">Section&nbsp;4.3.4</a>) represents the desired state of the <a href="#resources" class="smpl">target resource</a> if the request is successfully applied, whereas a representation in the payload of a POST request (<a href="#POST" id="rfc.xref.POST.1" title="POST">Section&nbsp;4.3.3</a>) represents an anonymous resource for providing data to be processed, such as the information that a user entered within
    11531151         an HTML form.
    11541152      </p>
    1155       <p id="rfc.section.3.3.p.4">Likewise, the payload of a <a href="#status.200" class="smpl">200 (OK)</a> response to GET (<a href="#GET" id="rfc.xref.GET.1" title="GET">Section&nbsp;4.3.1</a>) ought to contain a representation of the <a href="#resources" class="smpl">target resource</a>, as observed at the time of the message origination date (<a href="#header.date" id="rfc.xref.header.date.1" title="Date">Section&nbsp;7.1.1.2</a>), whereas the same status code in a response to POST might contain either a representation of the processing result or a
    1156          current representation of the target resource after applying the processing. Response messages with an error status code usually
    1157          contain a representation of the error condition, such that it describes the error state and what next steps are suggested
    1158          for resolving it.
    1159       </p>
    1160       <p id="rfc.section.3.3.p.5">Header fields that specifically describe the payload, rather than the associated representation, are referred to as "payload
     1153      <p id="rfc.section.3.3.p.3">In a response, the payload's purpose is defined by both the request method and the response status code. For example, the
     1154         payload of a <a href="#status.200" class="smpl">200 (OK)</a> response to GET (<a href="#GET" id="rfc.xref.GET.1" title="GET">Section&nbsp;4.3.1</a>) represents the current state of the <a href="#resources" class="smpl">target resource</a>, as observed at the time of the message origination date (<a href="#header.date" id="rfc.xref.header.date.1" title="Date">Section&nbsp;7.1.1.2</a>), whereas the payload of the same status code in a response to POST might represent either the processing result or the new
     1155         state of the target resource after applying the processing. Response messages with an error status code usually contain a
     1156         payload that represents the error condition, such that it describes the error state and what next steps are suggested for
     1157         resolving it.
     1158      </p>
     1159      <p id="rfc.section.3.3.p.4">Header fields that specifically describe the payload, rather than the associated representation, are referred to as "payload
    11611160         header fields". Payload header fields are defined in other parts of this specification, due to their impact on message parsing.
    11621161      </p>
    … …  
    12881287               <tr>
    12891288                  <td class="left">HEAD</td>
    1290                   <td class="left">Same as GET, but do not include a message body in the response.</td>
     1289                  <td class="left">Same as GET, but only transfer the status line and header block.</td>
    12911290                  <td class="left"><a href="#HEAD" id="rfc.xref.HEAD.1" title="HEAD">4.3.2</a></td>
    12921291               </tr>
    … …  
    14071406      <h3 id="rfc.section.4.3.2"><a href="#rfc.section.4.3.2">4.3.2</a>&nbsp;<a id="HEAD" href="#HEAD">HEAD</a></h3>
    14081407      <div id="rfc.iref.h.1"></div>
    1409       <p id="rfc.section.4.3.2.p.1">The HEAD method is identical to GET except that the server <em class="bcp14">MUST NOT</em> send a message body in the response. The metadata contained in the HTTP header fields in response to a HEAD request <em class="bcp14">SHOULD</em> be identical to the information sent in response to a GET request. This method can be used for obtaining metadata about the
     1408      <p id="rfc.section.4.3.2.p.1">The HEAD method is identical to GET except that the server <em class="bcp14">MUST NOT</em> send a message body in the response (i.e., the response terminates at the end of the header block). The metadata contained
     1409         in the HTTP header fields in response to a HEAD request <em class="bcp14">SHOULD</em> be identical to the information sent in response to a GET request. This method can be used for obtaining metadata about the
    14101410         selected representation without transferring the representation data. This method is often used for testing hypertext links
    14111411         for validity, accessibility, and recent modification.

  • draft-ietf-httpbis/latest/p2-semantics.xml

    r2090 r2091  
    848848<t>
    849849   Some HTTP messages transfer a complete or partial representation as the
    850    message "<x:dfn>payload</x:dfn>".  In some cases, a payload might only
    851    contain the associated representation's header fields (e.g., responses to
     850   message "<x:dfn>payload</x:dfn>".  In some cases, a payload might contain
     851   only the associated representation's header fields (e.g., responses to
    852852   HEAD) or only some part(s) of the representation data
    853853   (e.g., the <x:ref>206 (Partial Content)</x:ref> status code).
    … …  
    855855<t>
    856856   The purpose of a payload in a request is defined by the method semantics.
    857    In a response, the payload's purpose is defined by both the request method
    858    and the response status code.
    859 </t>
    860 <t>
    861857   For example, a representation in the payload of a PUT request
    862858   (<xref target="PUT"/>) represents the desired state of the <x:ref>target resource</x:ref>
    … …  
    867863</t>
    868864<t>
    869    Likewise, the payload of a <x:ref>200 (OK)</x:ref> response to GET
    870    (<xref target="GET"/>) ought to contain a representation of the
     865   In a response, the payload's purpose is defined by both the request method
     866   and the response status code.
     867   For example, the payload of a <x:ref>200 (OK)</x:ref> response to GET
     868   (<xref target="GET"/>) represents the current state of the
    871869   <x:ref>target resource</x:ref>, as observed at the time of the message
    872    origination date (<xref target="header.date"/>), whereas the same status
    873    code in a response to POST might contain either a representation of the
    874    processing result or a current representation of the target resource after
    875    applying the processing. Response messages with an error status code
    876    usually contain a representation of the error condition, such that it
    877    describes the error state and what next steps are suggested for resolving
    878    it.
     870   origination date (<xref target="header.date"/>), whereas the payload of
     871   the same status code in a response to POST might represent either the
     872   processing result or the new state of the target resource after applying
     873   the processing. Response messages with an error status code usually contain
     874   a payload that represents the error condition, such that it describes the
     875   error state and what next steps are suggested for resolving it.
    879876</t>
    880877<t>
    … …  
    10791076   <c><xref target="GET" format="counter"/></c>
    10801077   <c>HEAD</c>
    1081    <c>Same as GET, but do not include a message body in the response.</c>
     1078   <c>Same as GET, but only transfer the status line and header block.</c>
    10821079   <c><xref target="HEAD" format="counter"/></c>
    10831080   <c>POST</c>
    … …  
    12861283<t>
    12871284   The HEAD method is identical to GET except that the server &MUST-NOT;
    1288    send a message body in the response. The metadata contained
    1289    in the HTTP header fields in response to a HEAD request &SHOULD; be identical
    1290    to the information sent in response to a GET request. This method can
    1291    be used for obtaining metadata about the selected representation
    1292    without transferring the representation data. This method is
    1293    often used for testing hypertext links for validity, accessibility,
    1294    and recent modification.
     1285   send a message body in the response (i.e., the response terminates at the
     1286   end of the header block). The metadata contained in the HTTP header fields
     1287   in response to a HEAD request &SHOULD; be identical to the information sent
     1288   in response to a GET request. This method can be used for obtaining
     1289   metadata about the selected representation without transferring the
     1290   representation data. This method is often used for testing hypertext links
     1291   for validity, accessibility, and recent modification.
    12951292</t>
    12961293<t>
Note: See TracChangeset for help on using the changeset viewer.