Changeset 1158 for draft-ietf-httpbis/latest/p2-semantics.html

Timestamp:

10/03/11 08:40:45 (10 years ago)

Author:

fielding@…

Message:

Replaced the general prohibition on unrecognized Content-* header fields
with a specific prohibition of Content-Range (the only field for which
it is an actual problem) and a general requirement regarding checking
for consistency. Unfortunately, this required rewriting the entire
section on PUT to get rid of the misconceptions about storing resources
and reflect how PUT is actually implemented in practice.

Addresses #79, #102, #103, #104, #112, #180, #231, and #267

File:

• draft-ietf-httpbis/latest/p2-semantics.html (modified) (9 diffs)

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

@@ -359 +359 @@
   } 
   @bottom-center {
-       content: "Expires September 10, 2011"; 
+       content: "Expires September 11, 2011"; 
   } 
   @bottom-right {
@@ -409 +409 @@
       <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="2011-03-09">
+      <meta name="dct.issued" scheme="ISO8601" content="2011-03-10">
       <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, hypermedia information systems. HTTP has been in use by the World Wide Web global information initiative since 1990. This document is Part 2 of the seven-part specification that defines the protocol referred to as &#34;HTTP/1.1&#34; and, taken together, obsoletes RFC 2616. Part 2 defines the semantics of HTTP messages as expressed by request methods, request-header fields, response status codes, and response-header fields.">
@@ -440 +440 @@
             </tr>
             <tr>
-               <td class="left">Expires: September 10, 2011</td>
+               <td class="left">Expires: September 11, 2011</td>
                <td class="right">HP</td>
             </tr>
@@ -493 +493 @@
             <tr>
                <td class="left"></td>
-               <td class="right">March 9, 2011</td>
+               <td class="right">March 10, 2011</td>
             </tr>
          </tbody>
@@ -520 +520 @@
          in progress”.
       </p>
-      <p>This Internet-Draft will expire on September 10, 2011.</p>
+      <p>This Internet-Draft will expire on September 11, 2011.</p>
       <h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1>
       <p>Copyright © 2011 IETF Trust and the persons identified as the document authors. All rights reserved.</p>
@@ -1420 +1420 @@
       <div id="rfc.iref.m.5"></div>
       <h2 id="rfc.section.7.6"><a href="#rfc.section.7.6">7.6</a>&nbsp;<a id="PUT" href="#PUT">PUT</a></h2>
-      <p id="rfc.section.7.6.p.1">The PUT method requests that the enclosed representation be stored at the effective request URI. If the effective request
-         URI refers to an already existing resource, the enclosed representation <em class="bcp14">SHOULD</em> be considered a modified version of the one residing on the origin server. Otherwise, if the effective request URI does not
-         point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the
-         origin server can create the resource with that URI.
-      </p>
-      <p id="rfc.section.7.6.p.2">If a new resource is created at the effective request URI, the origin server <em class="bcp14">MUST</em> inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No
-         Content) response codes <em class="bcp14">SHOULD</em> be sent to indicate successful completion of the request.
-      </p>
-      <p id="rfc.section.7.6.p.3">If the target resource could not be created or modified, an appropriate error response <em class="bcp14">SHOULD</em> be given that reflects the nature of the problem. The recipient of the representation <em class="bcp14">MUST NOT</em> ignore any Content-* header fields (headers starting with the prefix "Content-") that it does not understand or implement
-         and <em class="bcp14">MUST</em> return a 501 (Not Implemented) response in such cases.
-      </p>
-      <p id="rfc.section.7.6.p.4">Responses to the PUT method are not cacheable. If a PUT request passes through a cache that has one or more stored responses
+      <p id="rfc.section.7.6.p.1">The PUT method is used to request that the state of the target resource be created or replaced with the state defined by the
+         representation enclosed in the request message payload. A successful PUT of a given representation would suggest that a subsequent
+         GET on that same target resource will result in an equivalent representation being returned in a 200 (OK) response. However,
+         there is no guarantee that such a state change will be observable, since the target resource might be acted upon by other
+         user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent GET is received.
+         A successful response only implies that the user agent's intent was achieved at the time of its processing by the origin server.
+      </p>
+      <p id="rfc.section.7.6.p.2">If the target resource does not have a current representation and the PUT successfully creates one, then the origin server <em class="bcp14">MUST</em> inform the user agent by sending a 201 (Created) response. If the target resource does have a current representation and that
+         representation is successfully modified in accordance with the state of the enclosed representation, then either a 200 (OK)
+         or 204 (No Content) response <em class="bcp14">SHOULD</em> be sent to indicate successful completion of the request.
+      </p>
+      <p id="rfc.section.7.6.p.3">Unrecognized header fields <em class="bcp14">SHOULD</em> be ignored (i.e., not saved as part of the resource state).
+      </p>
+      <p id="rfc.section.7.6.p.4">An origin server <em class="bcp14">SHOULD</em> verify that the PUT representation is consistent with any constraints which the server has for the target resource that cannot
+         or will not be changed by the PUT. This is particularly important when the origin server uses internal configuration information
+         related to the URI in order to set the values for representation metadata on GET responses. When a PUT representation is inconsistent
+         with the target resource, the origin server <em class="bcp14">SHOULD</em> either make them consistent, by transforming the representation or changing the resource configuration, or respond with a
+         409 (Conflict) status code and sufficient information to explain why the representation is unsuitable.
+      </p>
+      <p id="rfc.section.7.6.p.5">For example, if the target resource is configured to always have a Content-Type of "text/html" and the representation being
+         PUT has a Content-Type of "image/jpeg", then the origin server <em class="bcp14">SHOULD</em> do one of: (a) reconfigure the target resource to reflect the new media type; (b) transform the PUT representation to a format
+         consistent with that of the resource before saving it as the new resource state; or, (c) reject the request with a 409 response
+         indicating that the target resource is limited to "text/html", perhaps including a link to a different resource that would
+         be a suitable target for the new representation.
+      </p>
+      <p id="rfc.section.7.6.p.6">HTTP does not define exactly how a PUT method affects the state of an origin server beyond what can be expressed by the intent
+         of the user agent request and the semantics of the origin server response. It does not define what a resource might be, in
+         any sense of that word, beyond the interface provided via HTTP. It does not define how resource state is "stored", nor how
+         such storage might change as a result of a change in resource state, nor how the origin server translates resource state into
+         representations. Generally speaking, all implementation details behind the resource interface are intentionally hidden by
+         the server.
+      </p>
+      <p id="rfc.section.7.6.p.7">The fundamental difference between the POST and PUT methods is highlighted by the different intent for the target resource.
+         The target resource in a POST request is intended to handle the enclosed representation as a data-accepting process, such
+         as for a gateway to some other protocol or a document that accepts annotations. In contrast, the target resource in a PUT
+         request is intended to take the enclosed representation as a new or replacement value. Hence, the intent of PUT is idempotent
+         and visible to intermediaries, even though the exact effect is only known by the origin server.
+      </p>
+      <p id="rfc.section.7.6.p.8">Proper interpretation of a PUT request presumes that the user agent knows what target resource is desired. A service that
+         is intended to select a proper URI on behalf of the client, after receiving a state-changing request, <em class="bcp14">SHOULD</em> be implemented using the POST method rather than PUT. If the origin server will not make the requested PUT state change to
+         the target resource and instead wishes to have it applied to a different resource, such as when the resource has been moved
+         to a different URI, then the origin server <em class="bcp14">MUST</em> send a 301 (Moved Permanently) response; the user agent <em class="bcp14">MAY</em> then make its own decision regarding whether or not to redirect the request.
+      </p>
+      <p id="rfc.section.7.6.p.9">A PUT request applied to the target resource <em class="bcp14">MAY</em> have side-effects on other resources. For example, an article might have a URI for identifying "the current version" (a resource)
+         which is separate from the URIs identifying each particular version (different resources that at one point shared the same
+         state as the current version resource). A successful PUT request on "the current version" URI might therefore create a new
+         version resource in addition to changing the state of the target resource, and might also cause links to be added between
+         the related resources.
+      </p>
+      <p id="rfc.section.7.6.p.10">An origin server <em class="bcp14">SHOULD</em> reject any PUT request that contains a Content-Range header field, since it might be misinterpreted as partial content (or
+         might be partial content that is being mistakenly PUT as a full representation). Partial content updates are possible by targeting
+         a separately identified resource with state that overlaps a portion of the larger resource, or by using a different method
+         that has been specifically defined for partial updates (for example, the PATCH method defined in <a href="#RFC5789" id="rfc.xref.RFC5789.1"><cite title="PATCH Method for HTTP">[RFC5789]</cite></a>).
+      </p>
+      <p id="rfc.section.7.6.p.11">Responses to the PUT method are not cacheable. If a PUT request passes through a cache that has one or more stored responses
          for the effective request URI, those stored responses will be invalidated (see <a href="p6-cache.html#invalidation.after.updates.or.deletions" title="Request Methods that Invalidate">Section 2.5</a> of <a href="#Part6" id="rfc.xref.Part6.11"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>).
-      </p>
-      <p id="rfc.section.7.6.p.5">The fundamental difference between the POST and PUT requests is reflected in the different meaning of the effective request
-         URI. The URI in a POST request identifies the resource that will handle the enclosed representation. That resource might be
-         a data-accepting process, a gateway to some other protocol, or a document that accepts annotations. In contrast, the URI in
-         a PUT request identifies the resource for which enclosed representation is a new or replacement value; the user agent knows
-         what URI is intended and the server <em class="bcp14">MUST NOT</em> attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,
-         it <em class="bcp14">MUST</em> send a 301 (Moved Permanently) response; the user agent <em class="bcp14">MAY</em> then make its own decision regarding whether or not to redirect the request.
-      </p>
-      <p id="rfc.section.7.6.p.6">A single resource <em class="bcp14">MAY</em> be identified by many different URIs. For example, an article might have a URI for identifying "the current version" which
-         is separate from the URI identifying each particular version. In this case, a PUT request on a general URI might result in
-         several other URIs being defined by the origin server.
-      </p>
-      <p id="rfc.section.7.6.p.7">HTTP/1.1 does not define how a PUT method affects the state of an origin server.</p>
-      <p id="rfc.section.7.6.p.8">Header fields in a PUT request that are recognized as representation metadata <em class="bcp14">SHOULD</em> be applied to the resource created or modified by the PUT. Unrecognized header fields <em class="bcp14">SHOULD</em> be ignored.
       </p>
       <div id="rfc.iref.d.1"></div>
@@ -2631 +2660 @@
       <h2 id="rfc.references.2"><a href="#rfc.section.13.2" id="rfc.section.13.2">13.2</a> Informative References
       </h2>
-      <table>              
+      <table>                
          <tr>
             <td class="reference"><b id="RFC1945">[RFC1945]</b></td>
@@ -2665 +2694 @@
             <td class="reference"><b id="RFC5322">[RFC5322]</b></td>
             <td class="top">Resnick, P., “<a href="http://tools.ietf.org/html/rfc5322">Internet Message Format</a>”, RFC&nbsp;5322, October&nbsp;2008.
+            </td>
+         </tr>
+         <tr>
+            <td class="reference"><b id="RFC5789">[RFC5789]</b></td>
+            <td class="top">Dusseault, L. and J. Snell, “<a href="http://tools.ietf.org/html/rfc5789">PATCH Method for HTTP</a>”, RFC&nbsp;5789, March&nbsp;2010.
             </td>
          </tr>
@@ -3330 +3364 @@
                      </ul>
                   </li>
+                  <li><em>RFC5789</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC5789.1">7.6</a>, <a href="#RFC5789"><b>13.2</b></a></li>
                </ul>
             </li>