Changeset 2111 for draft-ietf-httpbis/latest

Timestamp:

11/01/13 08:39:05 (10 years ago)

Author:

fielding@…

Message:

ensure that a validator field sent in response to a successful PUT means something useful; addresses #22 (along with [2110])

Location:

draft-ietf-httpbis/latest

Files:

• p2-semantics.html (modified) (2 diffs)
• p2-semantics.xml (modified) (1 diff)

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

@@ -1476 +1476 @@
          the server.
       </p>
-      <p id="rfc.section.4.3.4.p.7">The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation.
+      <p id="rfc.section.4.3.4.p.7">An origin server <em class="bcp14">MUST NOT</em> send a validator header field (<a href="#response.validator" title="Validator Header Fields">Section&nbsp;7.2</a>), such as an <a href="p4-conditional.html#header.etag" class="smpl">ETag</a> or <a href="p4-conditional.html#header.last-modified" class="smpl">Last-Modified</a> field, in a successful response to PUT unless the request's representation data was saved without any transformation applied
+         to the body (i.e., the resource's new representation data is identical to the representation data received in the PUT request)
+         and the validator field value reflects the new representation. This requirement allows a user agent to know when the representation
+         body it has in memory remains current as a result of the PUT, thus not in need of retrieving again from the origin server,
+         and that the new validator(s) received in the response can be used for future conditional requests in order to prevent accidental
+         overwrites.
+      </p>
+      <p id="rfc.section.4.3.4.p.8">The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation.
          The target resource in a POST request is intended to handle the enclosed representation according to the resource's own semantics,
          whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. 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.4.3.4.p.8">Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. A service that
+      <p id="rfc.section.4.3.4.p.9">Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. A service that
          selects 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 an appropriate <a href="#status.3xx" class="smpl">3xx (Redirection)</a> 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.4.3.4.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)
+      <p id="rfc.section.4.3.4.p.10">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)
          that 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
@@ -1492 +1499 @@
          the related resources.
       </p>
-      <p id="rfc.section.4.3.4.p.10">An origin server <em class="bcp14">SHOULD</em> reject any PUT request that contains a <a href="p5-range.html#header.content-range" class="smpl">Content-Range</a> header field (<a href="p5-range.html#header.content-range" title="Content-Range">Section 5.2</a> of <a href="#Part5" id="rfc.xref.Part5.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>), since it might be misinterpreted as partial content (or might be partial content that is being mistakenly PUT as a full
+      <p id="rfc.section.4.3.4.p.11">An origin server <em class="bcp14">SHOULD</em> reject any PUT request that contains a <a href="p5-range.html#header.content-range" class="smpl">Content-Range</a> header field (<a href="p5-range.html#header.content-range" title="Content-Range">Section 5.2</a> of <a href="#Part5" id="rfc.xref.Part5.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Range Requests">[Part5]</cite></a>), 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.4.3.4.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
+      <p id="rfc.section.4.3.4.p.12">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 6</a> of <a href="#Part6" id="rfc.xref.Part6.6"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Caching">[Part6]</cite></a>).
       </p>

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

@@ -1443 +1443 @@
 </t>
 <t>
+   An origin server &MUST-NOT; send a validator header field
+   (<xref target="response.validator"/>), such as an <x:ref>ETag</x:ref> or
+   <x:ref>Last-Modified</x:ref> field, in a successful response to PUT unless
+   the request's representation data was saved without any transformation
+   applied to the body (i.e., the resource's new representation data is
+   identical to the representation data received in the PUT request) and the
+   validator field value reflects the new representation.
+   This requirement allows a user agent to know when the representation body
+   it has in memory remains current as a result of the PUT, thus not in need
+   of retrieving again from the origin server, and that the new validator(s)
+   received in the response can be used for future conditional requests in
+   order to prevent accidental overwrites.
+</t>
+<t>
    The fundamental difference between the POST and PUT methods is
    highlighted by the different intent for the enclosed representation.