Changeset 1158 for draft-ietf-httpbis/latest
- Timestamp:
- 10/03/11 08:40:45 (11 years ago)
- Location:
- draft-ietf-httpbis/latest
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p2-semantics.html
r1154 r1158 359 359 } 360 360 @bottom-center { 361 content: "Expires September 1 0, 2011";361 content: "Expires September 11, 2011"; 362 362 } 363 363 @bottom-right { … … 409 409 <meta name="dct.creator" content="Reschke, J. F."> 410 410 <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"> 412 412 <meta name="dct.replaces" content="urn:ietf:rfc:2616"> 413 413 <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 "HTTP/1.1" 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> 441 441 <tr> 442 <td class="left">Expires: September 1 0, 2011</td>442 <td class="left">Expires: September 11, 2011</td> 443 443 <td class="right">HP</td> 444 444 </tr> … … 493 493 <tr> 494 494 <td class="left"></td> 495 <td class="right">March 9, 2011</td>495 <td class="right">March 10, 2011</td> 496 496 </tr> 497 497 </tbody> … … 520 520 in progress”. 521 521 </p> 522 <p>This Internet-Draft will expire on September 1 0, 2011.</p>522 <p>This Internet-Draft will expire on September 11, 2011.</p> 523 523 <h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1> 524 524 <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> 1421 1421 <h2 id="rfc.section.7.6"><a href="#rfc.section.7.6">7.6</a> <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 1434 1477 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 request1437 URI. The URI in a POST request identifies the resource that will handle the enclosed representation. That resource might be1438 a data-accepting process, a gateway to some other protocol, or a document that accepts annotations. In contrast, the URI in1439 a PUT request identifies the resource for which enclosed representation is a new or replacement value; the user agent knows1440 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" which1444 is separate from the URI identifying each particular version. In this case, a PUT request on a general URI might result in1445 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.1449 1478 </p> 1450 1479 <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 2632 2661 </h2> 2633 <table> 2662 <table> 2634 2663 <tr> 2635 2664 <td class="reference"><b id="RFC1945">[RFC1945]</b></td> … … 2665 2694 <td class="reference"><b id="RFC5322">[RFC5322]</b></td> 2666 2695 <td class="top">Resnick, P., “<a href="http://tools.ietf.org/html/rfc5322">Internet Message Format</a>”, RFC 5322, October 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 5789, March 2010. 2667 2701 </td> 2668 2702 </tr> … … 3330 3364 </ul> 3331 3365 </li> 3366 <li><em>RFC5789</em> <a href="#rfc.xref.RFC5789.1">7.6</a>, <a href="#RFC5789"><b>13.2</b></a></li> 3332 3367 </ul> 3333 3368 </li> -
draft-ietf-httpbis/latest/p2-semantics.xml
r1154 r1158 1047 1047 <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/> 1048 1048 <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. 1056 1060 </t> 1057 1061 <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"/>). 1071 1156 </t> 1072 1157 <t> … … 1075 1160 request URI, those stored responses will be invalidated (see 1076 1161 &p6-invalid;). 1077 </t>1078 <t>1079 The fundamental difference between the POST and PUT requests is1080 reflected in the different meaning of the effective request URI. The URI in a1081 POST request identifies the resource that will handle the enclosed1082 representation. That resource might be a data-accepting process, a gateway to1083 some other protocol, or a document that accepts annotations.1084 In contrast, the URI in a PUT request identifies the resource for1085 which enclosed representation is a new or replacement value; the1086 user agent knows what URI is intended and the server &MUST-NOT; attempt1087 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 the1091 request.1092 </t>1093 <t>1094 A single resource &MAY; be identified by many different URIs. For1095 example, an article might have a URI for identifying "the current1096 version" which is separate from the URI identifying each particular1097 version. In this case, a PUT request on a general URI might result in1098 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 an1102 origin server.1103 </t>1104 <t>1105 Header fields in a PUT request that are recognized as representation1106 metadata &SHOULD; be applied to the resource created or modified by1107 the PUT. Unrecognized header fields &SHOULD; be ignored.1108 1162 </t> 1109 1163 </section> … … 3471 3525 </front> 3472 3526 <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' /> 3473 3541 </reference> 3474 3542
Note: See TracChangeset
for help on using the changeset viewer.