Changeset 2098 for draft-ietf-httpbis/latest

Timestamp:

07/01/13 09:02:41 (10 years ago)

Author:

fielding@…

Message:

(editorial) move notes on 406 to 300 and include a reference to Link; miscellaneous proofreading edits

Location:

draft-ietf-httpbis/latest

Files:

• p2-semantics.html (modified) (18 diffs)
• p2-semantics.xml (modified) (12 diffs)

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

@@ -449 +449 @@
   } 
   @bottom-center {
-       content: "Expires July 10, 2013"; 
+       content: "Expires July 11, 2013"; 
   } 
   @bottom-right {
@@ -494 +494 @@
       <meta name="dct.creator" content="Reschke, J. F.">
       <meta name="dct.identifier" content="urn:ietf:id:draft-ietf-httpbis-p2-semantics-latest">
-      <meta name="dct.issued" scheme="ISO8601" content="2013-01-06">
+      <meta name="dct.issued" scheme="ISO8601" content="2013-01-07">
       <meta name="dct.replaces" content="urn:ietf:rfc:2616">
       <meta name="dct.abstract" content="The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.">
@@ -522 +522 @@
             <tr>
                <td class="left">Intended status: Standards Track</td>
-               <td class="right">January 6, 2013</td>
+               <td class="right">January 7, 2013</td>
             </tr>
             <tr>
-               <td class="left">Expires: July 10, 2013</td>
+               <td class="left">Expires: July 11, 2013</td>
                <td class="right"></td>
             </tr>
@@ -553 +553 @@
          in progress”.
       </p>
-      <p>This Internet-Draft will expire on July 10, 2013.</p>
+      <p>This Internet-Draft will expire on July 11, 2013.</p>
       <h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1>
       <p>Copyright © 2013 IETF Trust and the persons identified as the document authors. All rights reserved.</p>
@@ -1580 +1580 @@
       <p id="rfc.section.4.3.7.p.6">A server generating a successful response to OPTIONS <em class="bcp14">SHOULD</em> send any header fields that might indicate optional features implemented by the server and applicable to the target resource
          (e.g., <a href="#header.allow" class="smpl">Allow</a>), including potential extensions not defined by this specification. The response payload, if any, might also describe the
-         communication options in a machine or human-readable representation. A standard format for such a payload is not defined by
-         this specification, but might be defined by future extensions to HTTP. A server <em class="bcp14">MUST</em> generate a <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> field with a value of "0" if no payload body is to be sent in the response.
+         communication options in a machine or human-readable representation. A standard format for such a representation is not defined
+         by this specification, but might be defined by future extensions to HTTP. A server <em class="bcp14">MUST</em> generate a <a href="p1-messaging.html#header.content-length" class="smpl">Content-Length</a> field with a value of "0" if no payload body is to be sent in the response.
       </p>
       <p id="rfc.section.4.3.7.p.7">A client <em class="bcp14">MAY</em> send a <a href="#header.max-forwards" class="smpl">Max-Forwards</a> header field in an OPTIONS request to target a specific recipient in the request chain (see <a href="#header.max-forwards" id="rfc.xref.header.max-forwards.1" title="Max-Forwards">Section&nbsp;5.1.2</a>). A proxy <em class="bcp14">MUST NOT</em> generate a Max-Forwards header field while forwarding a request unless that request was received with a Max-Forwards field.
@@ -2131 +2131 @@
       </p>
       <p id="rfc.section.6.p.3">For example, if an unrecognized status code of 471 is received by a client, the client can assume that there was something
-         wrong with its request and treat the response as if it had received a 400 status code. If the response includes a message
-         body, it will usually include a representation that explains the response status.
+         wrong with its request and treat the response as if it had received a 400 status code. The response message will usually contain
+         a representation that explains the status.
       </p>
       <p id="rfc.section.6.p.4">The first digit of the status-code defines the class of response. The last two digits do not have any categorization role.
@@ -2410 +2410 @@
       <div id="rfc.iref.72"></div>
       <h3 id="rfc.section.6.3.1"><a href="#rfc.section.6.3.1">6.3.1</a>&nbsp;<a id="status.200" href="#status.200">200 OK</a></h3>
-      <p id="rfc.section.6.3.1.p.1">The <dfn>200 (OK)</dfn> status code indicates that the request has succeeded. The payload sent in the response is dependent on the method used in
-         the request, for example: 
+      <p id="rfc.section.6.3.1.p.1">The <dfn>200 (OK)</dfn> status code indicates that the request has succeeded. The meaning of a payload sent in the response depends on the request
+         method, as follows: 
       </p>
       <dl>
@@ -2418 +2418 @@
          </dd>
          <dt>HEAD</dt>
-         <dd>the same representation as GET, except without the message body;</dd>
+         <dd>the same representation as GET, but without the representation data;</dd>
          <dt>POST</dt>
          <dd>a representation describing or containing the result of the action;</dd>
@@ -2440 +2440 @@
       <p id="rfc.section.6.3.3.p.1">The <dfn>202 (Accepted)</dfn> status code indicates that the request has been accepted for processing, but the processing has not been completed. The request
          might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility
-         for re-sending a status code from an asynchronous operation such as this.
+         in HTTP for re-sending a status code from an asynchronous operation.
       </p>
       <p id="rfc.section.6.3.3.p.2">The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process
          (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the
          server persist until the process is completed. The representation sent with this response ought to describe the request's
-         current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.
+         current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will
+         be fulfilled.
       </p>
       <div id="rfc.iref.72"></div>
@@ -2458 +2459 @@
       <h3 id="rfc.section.6.3.5"><a href="#rfc.section.6.3.5">6.3.5</a>&nbsp;<a id="status.204" href="#status.204">204 No Content</a></h3>
       <p id="rfc.section.6.3.5.p.1">The <dfn>204 (No Content)</dfn> status code indicates that the server has successfully fulfilled the request and that there is no additional content to send
-         in the response payload body. Metadata in the response header fields refer to the <a href="#resources" class="smpl">target resource</a> and its current representation after the requested action.
+         in the response payload body. Metadata in the response header fields refer to the <a href="#resources" class="smpl">target resource</a> and its selected representation after the requested action was applied.
       </p>
       <p id="rfc.section.6.3.5.p.2">For example, if a 204 status code is received in response to a PUT request and the response contains an <a href="p4-conditional.html#header.etag" class="smpl">ETag</a> header field, then the PUT was successful and the ETag field-value contains the entity-tag for the new representation of that
@@ -2472 +2473 @@
          automated data transfers to be prevalent, such as within distributed version control systems.
       </p>
-      <p id="rfc.section.6.3.5.p.5">A 204 response does not include a message body, and thus is always terminated by the first empty line after the header fields.</p>
+      <p id="rfc.section.6.3.5.p.5">A 204 response is terminated by the first empty line after the header fields because it cannot contain a message body.</p>
       <div id="rfc.iref.72"></div>
       <h3 id="rfc.section.6.3.6"><a href="#rfc.section.6.3.6">6.3.6</a>&nbsp;<a id="status.205" href="#status.205">205 Reset Content</a></h3>
@@ -2530 +2531 @@
          most appropriate representation(s) for its needs (<a href="#content.negotiation" title="Content Negotiation">Section&nbsp;3.4</a>).
       </p>
-      <p id="rfc.section.6.4.1.p.2">For request methods other than HEAD, the server <em class="bcp14">SHOULD</em> generate a payload in the 300 response containing a list of representation metadata and URI reference(s) from which the user
+      <p id="rfc.section.6.4.1.p.2">If the server has a preferred choice, the server <em class="bcp14">SHOULD</em> generate a <a href="#header.location" class="smpl">Location</a> header field containing a preferred choice's URI reference. The user agent <em class="bcp14">MAY</em> use the Location field value for automatic redirection.
+      </p>
+      <p id="rfc.section.6.4.1.p.3">For request methods other than HEAD, the server <em class="bcp14">SHOULD</em> generate a payload in the 300 response containing a list of representation metadata and URI reference(s) from which the user
          or user agent can choose the one most preferred. The user agent <em class="bcp14">MAY</em> make a selection from that list automatically, depending upon the list format, but this specification does not define a standard
          for such automatic selection.
       </p>
-      <p id="rfc.section.6.4.1.p.3">If the server has a preferred choice, the server <em class="bcp14">SHOULD</em> generate a <a href="#header.location" class="smpl">Location</a> header field containing a preferred choice's URI reference. The user agent <em class="bcp14">MAY</em> use the Location field value for automatic redirection.
-      </p>
       <p id="rfc.section.6.4.1.p.4">Caches <em class="bcp14">MAY</em> use a heuristic (see <a href="p6-cache.html#heuristic.freshness" title="Calculating Heuristic Freshness">Section 4.1.2</a> of <a href="#Part6" id="rfc.xref.Part6.12"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>) to determine freshness for 300 responses.
       </p>
+      <div class="note" id="rfc.section.6.4.1.p.5"> 
+         <p> <b>Note:</b> The original proposal for 300 defined the URI header field as providing a list of alternative representations, such that it
+            would be usable for 200, 300, and 406 responses and be transferred in responses to the HEAD method. However, lack of deployment
+            and disagreement over syntax led to both URI and Alternates (a subsequent proposal) being dropped from this specification.
+            It is possible to communicate the list using a set of Link header fields <a href="#RFC5988" id="rfc.xref.RFC5988.1"><cite title="Web Linking">[RFC5988]</cite></a>, each with a relationship of "alternate", though deployment is a chicken-and-egg problem.
+         </p> 
+      </div>
       <div id="rfc.iref.73"></div>
       <h3 id="rfc.section.6.4.2"><a href="#rfc.section.6.4.2">6.4.2</a>&nbsp;<a id="status.301" href="#status.301">301 Moved Permanently</a></h3>
@@ -2645 +2653 @@
       <p id="rfc.section.6.5.6.p.2">The server <em class="bcp14">SHOULD</em> generate a payload containing a list of available representation characteristics and corresponding resource identifiers from
          which the user or user agent can choose the one most appropriate. A user agent <em class="bcp14">MAY</em> automatically select the most appropriate choice from that list. However, this specification does not define any standard
-         for such automatic selection. [The original proposal for 406 defined the Alternates header field as providing a list of alternative
-         representations, such that it would be available for responses to the HEAD method, but lack of deployment led to Alternates
-         being dropped from the specification.]
+         for such automatic selection, as described in <a href="#status.300" id="rfc.xref.status.300.2" title="300 Multiple Choices">Section&nbsp;6.4.1</a>.
       </p>
       <div id="rfc.iref.74"></div>
@@ -3328 +3334 @@
                   <td class="left">300</td>
                   <td class="left">Multiple Choices</td>
-                  <td class="left"> <a href="#status.300" id="rfc.xref.status.300.2" title="300 Multiple Choices">Section&nbsp;6.4.1</a> 
+                  <td class="left"> <a href="#status.300" id="rfc.xref.status.300.3" title="300 Multiple Choices">Section&nbsp;6.4.1</a> 
                   </td>
                </tr>
@@ -3955 +3961 @@
       <h2 id="rfc.references.2"><a href="#rfc.section.11.2" id="rfc.section.11.2">11.2</a> Informative References
       </h2>
-      <table>                                        
+      <table>                                          
          <tr>
             <td class="reference"><b id="BCP13">[BCP13]</b></td>
@@ -4042 +4048 @@
          </tr>
          <tr>
+            <td class="reference"><b id="RFC5988">[RFC5988]</b></td>
+            <td class="top">Nottingham, M., “<a href="http://tools.ietf.org/html/rfc5988">Web Linking</a>”, RFC&nbsp;5988, October&nbsp;2010.
+            </td>
+         </tr>
+         <tr>
             <td class="reference"><b id="RFC6265">[RFC6265]</b></td>
             <td class="top"><a href="mailto:abarth@eecs.berkeley.edu" title="&#xA;        University of California, Berkeley&#xA;      ">Barth, A.</a>, “<a href="http://tools.ietf.org/html/rfc6265">HTTP State Management Mechanism</a>”, RFC&nbsp;6265, April&nbsp;2011.
@@ -4381 +4392 @@
             </li>
             <li><a id="rfc.index.3" href="#rfc.index.3"><b>3</b></a><ul>
-                  <li>300 Multiple Choices (status code)&nbsp;&nbsp;<a href="#rfc.xref.status.300.1">6.1</a>, <a href="#rfc.iref.73"><b>6.4.1</b></a>, <a href="#rfc.xref.status.300.2">8.2.3</a></li>
+                  <li>300 Multiple Choices (status code)&nbsp;&nbsp;<a href="#rfc.xref.status.300.1">6.1</a>, <a href="#rfc.iref.73"><b>6.4.1</b></a>, <a href="#rfc.xref.status.300.2">6.5.6</a>, <a href="#rfc.xref.status.300.3">8.2.3</a></li>
                   <li>301 Moved Permanently (status code)&nbsp;&nbsp;<a href="#rfc.xref.status.301.1">6.1</a>, <a href="#rfc.iref.73"><b>6.4.2</b></a>, <a href="#rfc.xref.status.301.2">8.2.3</a>, <a href="#rfc.xref.status.301.3">B</a></li>
                   <li>302 Found (status code)&nbsp;&nbsp;<a href="#rfc.xref.status.302.1">6.1</a>, <a href="#rfc.iref.73"><b>6.4.3</b></a>, <a href="#rfc.xref.status.302.2">8.2.3</a>, <a href="#rfc.xref.status.302.3">B</a></li>
@@ -4711 +4722 @@
                   <li><em>RFC5789</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC5789.1">4.3.4</a>, <a href="#RFC5789"><b>11.2</b></a></li>
                   <li><em>RFC5987</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC5987.1">8.3.1</a>, <a href="#RFC5987"><b>11.2</b></a></li>
+                  <li><em>RFC5988</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC5988.1">6.4.1</a>, <a href="#RFC5988"><b>11.2</b></a></li>
                   <li><em>RFC6265</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC6265.1">4.3.8</a>, <a href="#RFC6265"><b>11.2</b></a></li>
                   <li><em>RFC6266</em>&nbsp;&nbsp;<a href="#RFC6266"><b>11.2</b></a>, <a href="#rfc.xref.RFC6266.1">B</a></li>

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

@@ -1654 +1654 @@
    The response payload, if any, might also describe the communication options
    in a machine or human-readable representation. A standard format for such a
-   payload is not defined by this specification, but might be defined by
+   representation is not defined by this specification, but might be defined by
    future extensions to HTTP.
    A server &MUST; generate a <x:ref>Content-Length</x:ref> field with a value
@@ -2516 +2516 @@
    For example, if an unrecognized status code of 471 is received by a client,
    the client can assume that there was something wrong with its request and
-   treat the response as if it had received a 400 status code. If the response
-   includes a message body, it will usually include a representation that
-   explains the response status.
+   treat the response as if it had received a 400 status code. The response
+   message will usually contain a representation that explains the status.
 </t>
 <t>
@@ -2700 +2699 @@
 <t>
    The <x:dfn>200 (OK)</x:dfn> status code indicates that the request has
-   succeeded. The payload sent in the response
-   is dependent on the method used in the request, for example:
+   succeeded. The meaning of a payload sent in the response depends on the
+   request method, as follows:
   <list style="hanging">
     <t hangText="GET">
@@ -2707 +2706 @@
     </t>
     <t hangText="HEAD">
-      the same representation as GET, except without the message body;
+      the same representation as GET, but without the representation data;
     </t>
     <t hangText="POST">
@@ -2754 +2753 @@
    completed. The request might or might not eventually be acted upon, as it
    might be disallowed when processing actually takes place. There is no
-   facility for re-sending a status code from an asynchronous operation such
-   as this.
+   facility in HTTP for re-sending a status code from an asynchronous
+   operation.
 </t>
 <t>
@@ -2763 +2762 @@
    requiring that the user agent's connection to the server persist
    until the process is completed. The representation sent with this
-   response ought to describe the request's current status
-   and either a pointer to a status monitor or some estimate of when the
-   user can expect the request to be fulfilled.
+   response ought to describe the request's current status and point to
+   (or embed) a status monitor that can provide the user with an estimate of
+   when the request will be fulfilled.
 </t>
 </section>
@@ -2796 +2795 @@
    has successfully fulfilled the request and that there is no additional
    content to send in the response payload body. Metadata in the response
-   header fields refer to the <x:ref>target resource</x:ref> and its current representation
-   after the requested action.
+   header fields refer to the <x:ref>target resource</x:ref> and its
+   selected representation after the requested action was applied.
 </t>
 <t>
@@ -2822 +2821 @@
 </t>
 <t>
-   A 204 response does not include a message body, and thus is always
-   terminated by the first empty line after the header fields.
+   A 204 response is terminated by the first empty line after the header
+   fields because it cannot contain a message body.
 </t>
 </section>
@@ -2941 +2940 @@
 <t>
    The <x:dfn>300 (Multiple Choices)</x:dfn> status code indicates that the
-   <x:ref>target resource</x:ref> has more than one representation, each with its own more
-   specific identifier, and information about the alternatives is being
-   provided so that the user (or user agent) can select a preferred
+   <x:ref>target resource</x:ref> has more than one representation, each with
+   its own more specific identifier, and information about the alternatives is
+   being provided so that the user (or user agent) can select a preferred
    representation by redirecting its request to one or more of those
    identifiers. In other words, the server desires that the user agent engage
    in reactive negotiation to select the most appropriate representation(s)
    for its needs (&content-negotiation;).
+</t>
+<t>
+   If the server has a preferred choice, the server &SHOULD; generate a
+   <x:ref>Location</x:ref> header field containing a preferred choice's URI
+   reference. The user agent &MAY; use the Location field value for automatic
+   redirection.
 </t>
 <t>
@@ -2958 +2963 @@
 </t>
 <t>
-   If the server has a preferred choice, the server &SHOULD; generate a
-   <x:ref>Location</x:ref> header field containing a preferred choice's URI
-   reference. The user agent &MAY; use the Location field value for automatic
-   redirection.
-</t>
-<t>
    Caches &MAY; use a heuristic (see &p6-heuristic;) to determine 
    freshness for 300 responses.
 </t>
-
+<x:note>
+  <t>
+   &Note; The original proposal for 300 defined the URI header field as
+   providing a list of alternative representations, such that it would be
+   usable for 200, 300, and 406 responses and be transferred in responses to
+   the HEAD method. However, lack of deployment and disagreement over syntax
+   led to both URI and Alternates (a subsequent proposal) being dropped from
+   this specification. It is possible to communicate the list using a set of
+   Link header fields <xref target="RFC5988"/>, each with a relationship of
+   "alternate", though deployment is a chicken-and-egg problem.
+  </t>
+</x:note>
 </section>
 
@@ -3221 +3231 @@
    A user agent &MAY; automatically select the most appropriate choice from
    that list. However, this specification does not define any standard for
-   such automatic selection. [The original proposal for 406 defined the
-   Alternates header field as providing a list of alternative representations,
-   such that it would be available for responses to the HEAD method, but lack
-   of deployment led to Alternates being dropped from the specification.]
+   such automatic selection, as described in <xref target="status.300"/>.
 </t>
 </section>
@@ -5516 +5523 @@
 </reference>
 
+<reference anchor='RFC5988'>
+  <front>
+    <title>Web Linking</title>
+    <author initials='M.' surname='Nottingham' fullname='M. Nottingham'>
+    <organization /></author>
+    <date year='2010' month='October' />
+  </front>
+  <seriesInfo name='RFC' value='5988' />
+</reference>
+
 <reference anchor="RFC6265">
   <front>