* WGs marked with an * asterisk has had at least one new draft made available during the last 5 days

Changeset 1158


Ignore:
Timestamp:
2011-03-10 00:40:45 (4 years ago)
Author:
fielding@gbiv.com
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

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

Legend:

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

    r1154 r1158  
    359359  }  
    360360  @bottom-center { 
    361        content: "Expires September 10, 2011";  
     361       content: "Expires September 11, 2011";  
    362362  }  
    363363  @bottom-right { 
     
    409409      <meta name="dct.creator" content="Reschke, J. F."> 
    410410      <meta name="dct.identifier" content="urn:ietf:id:draft-ietf-httpbis-p2-semantics-latest"> 
    411       <meta name="dct.issued" scheme="ISO8601" content="2011-03-09"> 
     411      <meta name="dct.issued" scheme="ISO8601" content="2011-03-10"> 
    412412      <meta name="dct.replaces" content="urn:ietf:rfc:2616"> 
    413413      <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."> 
     
    440440            </tr> 
    441441            <tr> 
    442                <td class="left">Expires: September 10, 2011</td> 
     442               <td class="left">Expires: September 11, 2011</td> 
    443443               <td class="right">HP</td> 
    444444            </tr> 
     
    493493            <tr> 
    494494               <td class="left"></td> 
    495                <td class="right">March 9, 2011</td> 
     495               <td class="right">March 10, 2011</td> 
    496496            </tr> 
    497497         </tbody> 
     
    520520         in progress”. 
    521521      </p> 
    522       <p>This Internet-Draft will expire on September 10, 2011.</p> 
     522      <p>This Internet-Draft will expire on September 11, 2011.</p> 
    523523      <h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1> 
    524524      <p>Copyright © 2011 IETF Trust and the persons identified as the document authors. All rights reserved.</p> 
     
    14201420      <div id="rfc.iref.m.5"></div> 
    14211421      <h2 id="rfc.section.7.6"><a href="#rfc.section.7.6">7.6</a>&nbsp;<a id="PUT" href="#PUT">PUT</a></h2> 
    1422       <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 
    1423          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 
    1424          point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the 
    1425          origin server can create the resource with that URI. 
    1426       </p> 
    1427       <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 
    1428          Content) response codes <em class="bcp14">SHOULD</em> be sent to indicate successful completion of the request. 
    1429       </p> 
    1430       <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 
    1431          and <em class="bcp14">MUST</em> return a 501 (Not Implemented) response in such cases. 
    1432       </p> 
    1433       <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 
     1422      <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 
     1423         representation enclosed in the request message payload. A successful PUT of a given representation would suggest that a subsequent 
     1424         GET on that same target resource will result in an equivalent representation being returned in a 200 (OK) response. However, 
     1425         there is no guarantee that such a state change will be observable, since the target resource might be acted upon by other 
     1426         user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent GET is received. 
     1427         A successful response only implies that the user agent's intent was achieved at the time of its processing by the origin server. 
     1428      </p> 
     1429      <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 
     1430         representation is successfully modified in accordance with the state of the enclosed representation, then either a 200 (OK) 
     1431         or 204 (No Content) response <em class="bcp14">SHOULD</em> be sent to indicate successful completion of the request. 
     1432      </p> 
     1433      <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). 
     1434      </p> 
     1435      <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 
     1436         or will not be changed by the PUT. This is particularly important when the origin server uses internal configuration information 
     1437         related to the URI in order to set the values for representation metadata on GET responses. When a PUT representation is inconsistent 
     1438         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 
     1439         409 (Conflict) status code and sufficient information to explain why the representation is unsuitable. 
     1440      </p> 
     1441      <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 
     1442         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 
     1443         consistent with that of the resource before saving it as the new resource state; or, (c) reject the request with a 409 response 
     1444         indicating that the target resource is limited to "text/html", perhaps including a link to a different resource that would 
     1445         be a suitable target for the new representation. 
     1446      </p> 
     1447      <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 
     1448         of the user agent request and the semantics of the origin server response. It does not define what a resource might be, in 
     1449         any sense of that word, beyond the interface provided via HTTP. It does not define how resource state is "stored", nor how 
     1450         such storage might change as a result of a change in resource state, nor how the origin server translates resource state into 
     1451         representations. Generally speaking, all implementation details behind the resource interface are intentionally hidden by 
     1452         the server. 
     1453      </p> 
     1454      <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. 
     1455         The target resource in a POST request is intended to handle the enclosed representation as a data-accepting process, such 
     1456         as for a gateway to some other protocol or a document that accepts annotations. In contrast, the target resource in a PUT 
     1457         request is intended to take the enclosed representation as a new or replacement value. Hence, the intent of PUT is idempotent 
     1458         and visible to intermediaries, even though the exact effect is only known by the origin server. 
     1459      </p> 
     1460      <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 
     1461         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 
     1462         the target resource and instead wishes to have it applied to a different resource, such as when the resource has been moved 
     1463         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. 
     1464      </p> 
     1465      <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) 
     1466         which is separate from the URIs identifying each particular version (different resources that at one point shared the same 
     1467         state as the current version resource). A successful PUT request on "the current version" URI might therefore create a new 
     1468         version resource in addition to changing the state of the target resource, and might also cause links to be added between 
     1469         the related resources. 
     1470      </p> 
     1471      <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 
     1472         might be partial content that is being mistakenly PUT as a full representation). Partial content updates are possible by targeting 
     1473         a separately identified resource with state that overlaps a portion of the larger resource, or by using a different method 
     1474         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>). 
     1475      </p> 
     1476      <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 
    14341477         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>). 
    1435       </p> 
    1436       <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 
    1437          URI. The URI in a POST request identifies the resource that will handle the enclosed representation. That resource might be 
    1438          a data-accepting process, a gateway to some other protocol, or a document that accepts annotations. In contrast, the URI in 
    1439          a PUT request identifies the resource for which enclosed representation is a new or replacement value; the user agent knows 
    1440          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, 
    1441          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. 
    1442       </p> 
    1443       <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 
    1444          is separate from the URI identifying each particular version. In this case, a PUT request on a general URI might result in 
    1445          several other URIs being defined by the origin server. 
    1446       </p> 
    1447       <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> 
    1448       <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. 
    14491478      </p> 
    14501479      <div id="rfc.iref.d.1"></div> 
     
    26312660      <h2 id="rfc.references.2"><a href="#rfc.section.13.2" id="rfc.section.13.2">13.2</a> Informative References 
    26322661      </h2> 
    2633       <table>               
     2662      <table>                 
    26342663         <tr> 
    26352664            <td class="reference"><b id="RFC1945">[RFC1945]</b></td> 
     
    26652694            <td class="reference"><b id="RFC5322">[RFC5322]</b></td> 
    26662695            <td class="top">Resnick, P., “<a href="http://tools.ietf.org/html/rfc5322">Internet Message Format</a>”, RFC&nbsp;5322, October&nbsp;2008. 
     2696            </td> 
     2697         </tr> 
     2698         <tr> 
     2699            <td class="reference"><b id="RFC5789">[RFC5789]</b></td> 
     2700            <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. 
    26672701            </td> 
    26682702         </tr> 
     
    33303364                     </ul> 
    33313365                  </li> 
     3366                  <li><em>RFC5789</em>&nbsp;&nbsp;<a href="#rfc.xref.RFC5789.1">7.6</a>, <a href="#RFC5789"><b>13.2</b></a></li> 
    33323367               </ul> 
    33333368            </li> 
  • draft-ietf-httpbis/latest/p2-semantics.xml

    r1154 r1158  
    10471047  <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/> 
    10481048<t> 
    1049    The PUT method requests that the enclosed representation be stored at the 
    1050    effective request URI. If the effective request URI refers to an already 
    1051    existing resource, the enclosed representation &SHOULD; be considered a 
    1052    modified version of the one residing on the origin server. Otherwise, if the 
    1053    effective request URI does not point to an existing resource, and that URI is 
    1054    capable of being defined as a new resource by the requesting user 
    1055    agent, the origin server can create the resource with that URI. 
     1049   The PUT method is used to request that the state of the target resource 
     1050   be created or replaced with the state defined by the representation 
     1051   enclosed in the request message payload.  A successful PUT of a given 
     1052   representation would suggest that a subsequent GET on that same target 
     1053   resource will result in an equivalent representation being returned in 
     1054   a 200 (OK) response.  However, there is no guarantee that such a state 
     1055   change will be observable, since the target resource might be acted 
     1056   upon by other user agents in parallel, or might be subject to dynamic 
     1057   processing by the origin server, before any subsequent GET is received. 
     1058   A successful response only implies that the user agent's intent was 
     1059   achieved at the time of its processing by the origin server. 
    10561060</t> 
    10571061<t>    
    1058    If a new resource is created at the effective request URI, the origin 
    1059    server &MUST; inform the user agent 
    1060    via the 201 (Created) response. If an existing resource is modified, 
    1061    either the 200 (OK) or 204 (No Content) response codes &SHOULD; be sent 
    1062    to indicate successful completion of the request. 
    1063 </t> 
    1064 <t>    
    1065    If the target resource could not be created or modified, an appropriate 
    1066    error response &SHOULD; be given that reflects the nature of the problem. 
    1067    The recipient of the representation &MUST-NOT; ignore any Content-* 
    1068    header fields (headers starting with the prefix "Content-") that it does 
    1069    not understand or implement 
    1070    and &MUST; return a 501 (Not Implemented) response in such cases. 
     1062   If the target resource does not have a current representation and 
     1063   the PUT successfully creates one, then the origin server &MUST; inform 
     1064   the user agent by sending a 201 (Created) response.  If the target 
     1065   resource does have a current representation and that representation is 
     1066   successfully modified in accordance with the state of the enclosed 
     1067   representation, then either a 200 (OK) or 204 (No Content) response 
     1068   &SHOULD; be sent to indicate successful completion of the request. 
     1069</t> 
     1070<t> 
     1071   Unrecognized header fields &SHOULD; be ignored (i.e., not saved 
     1072   as part of the resource state). 
     1073</t> 
     1074<t> 
     1075   An origin server &SHOULD; verify that the PUT representation is 
     1076   consistent with any constraints which the server has for the target 
     1077   resource that cannot or will not be changed by the PUT.  This is 
     1078   particularly important when the origin server uses internal 
     1079   configuration information related to the URI in order to set the 
     1080   values for representation metadata on GET responses.  When a PUT 
     1081   representation is inconsistent with the target resource, the origin 
     1082   server &SHOULD; either make them consistent, by transforming the 
     1083   representation or changing the resource configuration, or respond 
     1084   with a 409 (Conflict) status code and sufficient information 
     1085   to explain why the representation is unsuitable. 
     1086</t> 
     1087<t> 
     1088   For example, if the target resource is configured to always have a 
     1089   Content-Type of "text/html" and the representation being PUT has a 
     1090   Content-Type of "image/jpeg", then the origin server &SHOULD; do one of: 
     1091   (a) reconfigure the target resource to reflect the new media type; 
     1092   (b) transform the PUT representation to a format consistent with that 
     1093   of the resource before saving it as the new resource state; or, 
     1094   (c) reject the request with a 409 response indicating that the target 
     1095   resource is limited to "text/html", perhaps including a link to a 
     1096   different resource that would be a suitable target for the new 
     1097   representation. 
     1098</t> 
     1099<t> 
     1100   HTTP does not define exactly how a PUT method affects the state 
     1101   of an origin server beyond what can be expressed by the intent of 
     1102   the user agent request and the semantics of the origin server response. 
     1103   It does not define what a resource might be, in any sense of that 
     1104   word, beyond the interface provided via HTTP.  It does not define 
     1105   how resource state is "stored", nor how such storage might change 
     1106   as a result of a change in resource state, nor how the origin server 
     1107   translates resource state into representations.  Generally speaking, 
     1108   all implementation details behind the resource interface are 
     1109   intentionally hidden by the server. 
     1110</t> 
     1111<t> 
     1112   The fundamental difference between the POST and PUT methods is 
     1113   highlighted by the different intent for the target resource. 
     1114   The target resource in a POST request is intended to handle the 
     1115   enclosed representation as a data-accepting process, such as for 
     1116   a gateway to some other protocol or a document that accepts annotations. 
     1117   In contrast, the target resource in a PUT request is intended to 
     1118   take the enclosed representation as a new or replacement value. 
     1119   Hence, the intent of PUT is idempotent and visible to intermediaries, 
     1120   even though the exact effect is only known by the origin server. 
     1121</t> 
     1122<t> 
     1123   Proper interpretation of a PUT request presumes that the user agent 
     1124   knows what target resource is desired.  A service that is intended 
     1125   to select a proper URI on behalf of the client, after receiving 
     1126   a state-changing request, &SHOULD; be implemented using the POST 
     1127   method rather than PUT.  If the origin server will not make the 
     1128   requested PUT state change to the target resource and instead 
     1129   wishes to have it applied to a different resource, such as when the 
     1130   resource has been moved to a different URI, then the origin server 
     1131   &MUST; send a 301 (Moved Permanently) response; the user agent &MAY; 
     1132   then make its own decision regarding whether or not to redirect the 
     1133   request. 
     1134</t> 
     1135<t> 
     1136   A PUT request applied to the target resource &MAY; have side-effects 
     1137   on other resources.  For example, an article might have a URI for 
     1138   identifying "the current version" (a resource) which is separate 
     1139   from the URIs identifying each particular version (different 
     1140   resources that at one point shared the same state as the current version 
     1141   resource).  A successful PUT request on "the current version" URI might 
     1142   therefore create a new version resource in addition to changing the 
     1143   state of the target resource, and might also cause links to be added 
     1144   between the related resources. 
     1145</t> 
     1146<t> 
     1147   An origin server &SHOULD; reject any PUT request that contains a 
     1148   Content-Range header field, since it might be misinterpreted as 
     1149   partial content (or might be partial content that is being mistakenly 
     1150   PUT as a full representation).  Partial content updates are 
     1151   possible by targeting a separately identified resource with state 
     1152   that overlaps a portion of the larger resource, or by using a 
     1153   different method that has been specifically defined for partial 
     1154   updates (for example, the PATCH method defined in 
     1155   <xref target="RFC5789"/>). 
    10711156</t> 
    10721157<t> 
     
    10751160   request URI, those stored responses will be invalidated (see 
    10761161   &p6-invalid;). 
    1077 </t> 
    1078 <t> 
    1079    The fundamental difference between the POST and PUT requests is 
    1080    reflected in the different meaning of the effective request URI. The URI in a 
    1081    POST request identifies the resource that will handle the enclosed 
    1082    representation. That resource might be a data-accepting process, a gateway to 
    1083    some other protocol, or a document that accepts annotations. 
    1084    In contrast, the URI in a PUT request identifies the resource for 
    1085    which enclosed representation is a new or replacement value; the 
    1086    user agent knows what URI is intended and the server &MUST-NOT; attempt 
    1087    to apply the request to some other resource. 
    1088    If the server desires that the request be applied to a different URI, 
    1089    it &MUST; send a 301 (Moved Permanently) response; the user agent &MAY; 
    1090    then make its own decision regarding whether or not to redirect the 
    1091    request. 
    1092 </t> 
    1093 <t> 
    1094    A single resource &MAY; be identified by many different URIs. For 
    1095    example, an article might have a URI for identifying "the current 
    1096    version" which is separate from the URI identifying each particular 
    1097    version. In this case, a PUT request on a general URI might result in 
    1098    several other URIs being defined by the origin server. 
    1099 </t> 
    1100 <t> 
    1101    HTTP/1.1 does not define how a PUT method affects the state of an 
    1102    origin server. 
    1103 </t> 
    1104 <t> 
    1105    Header fields in a PUT request that are recognized as representation 
    1106    metadata &SHOULD; be applied to the resource created or modified by 
    1107    the PUT.  Unrecognized header fields &SHOULD; be ignored. 
    11081162</t> 
    11091163</section> 
     
    34713525  </front>  
    34723526  <seriesInfo name="RFC" value="5322"/> 
     3527</reference> 
     3528 
     3529<reference anchor='RFC5789'> 
     3530  <front> 
     3531    <title>PATCH Method for HTTP</title> 
     3532    <author initials='L.' surname='Dusseault' fullname='L. Dusseault'> 
     3533      <organization>Linden Lab</organization> 
     3534    </author> 
     3535    <author initials='J.' surname='Snell' fullname='J. Snell'> 
     3536      <organization /> 
     3537    </author> 
     3538    <date year='2010' month='March' /> 
     3539  </front> 
     3540  <seriesInfo name='RFC' value='5789' /> 
    34733541</reference> 
    34743542 
Note: See TracChangeset for help on using the changeset viewer.