Changeset 1162 for draft-ietf-httpbis/latest/p2-semantics.html
- Timestamp:
- 11/03/11 05:42:12 (11 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p2-semantics.html
r1160 r1162 774 774 <WWW-Authenticate, defined in <a href="#Part7" id="rfc.xref.Part7.4"><cite title="HTTP/1.1, part 7: Authentication">[Part7]</cite></a>, <a href="p7-auth.html#header.www-authenticate" title="WWW-Authenticate">Section 4.4</a>> 775 775 </pre><h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> <a id="method" href="#method">Method</a></h1> 776 <p id="rfc.section.2.p.1">The Method token indicates the method to be performed on the target resource (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 4.3</a> of <a href="#Part1" id="rfc.xref.Part1.17"><cite title="HTTP/1.1, part 1: URIs, Connections, and Message Parsing">[Part1]</cite></a>). The method is case-sensitive.776 <p id="rfc.section.2.p.1">The Method token indicates the request method to be performed on the target resource (<a href="p1-messaging.html#effective.request.uri" title="Effective Request URI">Section 4.3</a> of <a href="#Part1" id="rfc.xref.Part1.17"><cite title="HTTP/1.1, part 1: URIs, Connections, and Message Parsing">[Part1]</cite></a>). The method is case-sensitive. 777 777 </p> 778 778 <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.1"></span> <a href="#method" class="smpl">Method</a> = <a href="#core.rules" class="smpl">token</a> … … 829 829 </table> 830 830 </div> 831 <p id="rfc.section.2.1.p.2">Note that this list is not exhaustive — it does not include methods defined in other specifications.</p>831 <p id="rfc.section.2.1.p.2">Note that this list is not exhaustive — it does not include request methods defined in other specifications.</p> 832 832 <h2 id="rfc.section.2.2"><a href="#rfc.section.2.2">2.2</a> <a id="method.registry" href="#method.registry">Method Registry</a></h2> 833 833 <p id="rfc.section.2.2.p.1">The HTTP Method Registry defines the name space for the Method token in the Request line of an HTTP request.</p> … … 1309 1309 </p> 1310 1310 <h1 id="rfc.section.7"><a href="#rfc.section.7">7.</a> <a id="method.definitions" href="#method.definitions">Method Definitions</a></h1> 1311 <p id="rfc.section.7.p.1">The set of common methods for HTTP/1.1 is defined below. Although this set can be expanded, additional methods cannot be assumed1312 to share the same semantics for separately extended clients and servers.1311 <p id="rfc.section.7.p.1">The set of common request methods for HTTP/1.1 is defined below. Although this set can be expanded, additional methods cannot 1312 be assumed to share the same semantics for separately extended clients and servers. 1313 1313 </p> 1314 1314 <h2 id="rfc.section.7.1"><a href="#rfc.section.7.1">7.1</a> <a id="safe.and.idempotent" href="#safe.and.idempotent">Safe and Idempotent Methods</a></h2> … … 1318 1318 the user to be aware of any actions they take which might have an unexpected significance to themselves or others. 1319 1319 </p> 1320 <p id="rfc.section.7.1.1.p.2">In particular, the convention has been established that the GET, HEAD, OPTIONS, and TRACE methods <em class="bcp14">SHOULD NOT</em> have the significance of taking an action other than retrieval. Thesemethods ought to be considered "<dfn id="safe">safe</dfn>". This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is1320 <p id="rfc.section.7.1.1.p.2">In particular, the convention has been established that the GET, HEAD, OPTIONS, and TRACE request methods <em class="bcp14">SHOULD NOT</em> have the significance of taking an action other than retrieval. These request methods ought to be considered "<dfn id="safe">safe</dfn>". This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is 1321 1321 made aware of the fact that a possibly unsafe action is being requested. 1322 1322 </p> … … 1327 1327 <div id="rfc.iref.i.1"></div> 1328 1328 <h3 id="rfc.section.7.1.2"><a href="#rfc.section.7.1.2">7.1.2</a> <a id="idempotent.methods" href="#idempotent.methods">Idempotent Methods</a></h3> 1329 <p id="rfc.section.7.1.2.p.1"> Methods can also have the property of "idempotence" in that, aside from error or expiration issues, the intended effect of1330 multiple identical requests is the same as for a single request. The methods PUT, DELETE, and all safemethods are idempotent.1329 <p id="rfc.section.7.1.2.p.1">Request methods can also have the property of "idempotence" in that, aside from error or expiration issues, the intended effect 1330 of multiple identical requests is the same as for a single request. PUT, DELETE, and all safe request methods are idempotent. 1331 1331 It is important to note that idempotence refers only to changes requested by the client: a server is free to change its state 1332 1332 due to multiple requests for the purpose of tracking those requests, versioning of results, etc. … … 1335 1335 <div id="rfc.iref.o.1"></div> 1336 1336 <div id="rfc.iref.m.1"></div> 1337 <p id="rfc.section.7.2.p.1">The OPTIONS method re presents a request for information about the communication options available on the request/response1338 chain identified by the effective request URI. This method allows the client to determine the options and/or requirements1339 associated with a resource,or the capabilities of a server, without implying a resource action or initiating a resource retrieval.1340 </p> 1341 <p id="rfc.section.7.2.p.2">Responses to th ismethod are not cacheable.</p>1337 <p id="rfc.section.7.2.p.1">The OPTIONS method requests information about the communication options available on the request/response chain identified 1338 by the effective request URI. This method allows a client to determine the options and/or requirements associated with a resource, 1339 or the capabilities of a server, without implying a resource action or initiating a resource retrieval. 1340 </p> 1341 <p id="rfc.section.7.2.p.2">Responses to the OPTIONS method are not cacheable.</p> 1342 1342 <p id="rfc.section.7.2.p.3">If the OPTIONS request includes a message-body (as indicated by the presence of Content-Length or Transfer-Encoding), then 1343 1343 the media type <em class="bcp14">MUST</em> be indicated by a Content-Type field. Although this specification does not define any use for such a body, future extensions … … 1361 1361 <div id="rfc.iref.g.5"></div> 1362 1362 <div id="rfc.iref.m.2"></div> 1363 <p id="rfc.section.7.3.p.1">The GET method means retrieve whatever information (in the form of a representation) currently corresponds tothe target resource.</p>1363 <p id="rfc.section.7.3.p.1">The GET method requests transfer of a current representation of the target resource.</p> 1364 1364 <p id="rfc.section.7.3.p.2">If the target resource is a data-producing process, it is the produced data which shall be returned as the representation 1365 1365 in the response and not the source text of the process, unless that text happens to be the output of the process. 1366 1366 </p> 1367 1367 <p id="rfc.section.7.3.p.3">The semantics of the GET method change to a "conditional GET" if the request message includes an If-Modified-Since, If-Unmodified-Since, 1368 If-Match, If-None-Match, or If-Range header field. A conditional GET method requests that the representation be transferred1369 only under the circumstances described by the conditional header field(s). The conditional GET method is intended to reduce1370 unnecessary network usage by allowing cached representations to be refreshed without requiring multiple requests or transferring1371 dataalready held by the client.1368 If-Match, If-None-Match, or If-Range header field. A conditional GET requests that the representation be transferred only 1369 under the circumstances described by the conditional header field(s). The conditional GET request is intended to reduce unnecessary 1370 network usage by allowing cached representations to be refreshed without requiring multiple requests or transferring data 1371 already held by the client. 1372 1372 </p> 1373 1373 <p id="rfc.section.7.3.p.4">The semantics of the GET method change to a "partial GET" if the request message includes a Range header field. A partial 1374 GET requests that only part of the representation be transferred, as described in <a href="p5-range.html#header.range" title="Range">Section 5.4</a> of <a href="#Part5" id="rfc.xref.Part5.10"><cite title="HTTP/1.1, part 5: Range Requests and Partial Responses">[Part5]</cite></a>. The partial GET method is intended to reduce unnecessary network usage by allowing partially-retrieved representations to1375 be completed without transferring data already held by the client.1374 GET requests that only part of the representation be transferred, as described in <a href="p5-range.html#header.range" title="Range">Section 5.4</a> of <a href="#Part5" id="rfc.xref.Part5.10"><cite title="HTTP/1.1, part 5: Range Requests and Partial Responses">[Part5]</cite></a>. The partial GET request is intended to reduce unnecessary network usage by allowing partially-retrieved representations 1375 to be completed without transferring data already held by the client. 1376 1376 </p> 1377 1377 <p id="rfc.section.7.3.p.5">The response to a GET request is cacheable and <em class="bcp14">MAY</em> be used to satisfy subsequent GET and HEAD requests (see <a href="#Part6" id="rfc.xref.Part6.8"><cite title="HTTP/1.1, part 6: Caching">[Part6]</cite></a>). … … 1393 1393 <div id="rfc.iref.m.4"></div> 1394 1394 <h2 id="rfc.section.7.5"><a href="#rfc.section.7.5">7.5</a> <a id="POST" href="#POST">POST</a></h2> 1395 <p id="rfc.section.7.5.p.1">The POST method is used to request that the origin server accept the representation enclosed in the request as data to be1396 processedby the target resource. POST is designed to allow a uniform method to cover the following functions:1395 <p id="rfc.section.7.5.p.1">The POST method requests that the origin server accept the representation enclosed in the request as data to be processed 1396 by the target resource. POST is designed to allow a uniform method to cover the following functions: 1397 1397 </p> 1398 1398 <ul> … … 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 is used to request that the state of the target resource be created or replaced with the state defined by the1423 representation enclosed in the request message payload. A successful PUT of a given representation would suggest that a subsequent1424 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 other1426 user agents in parallel, or might be subject to dynamic processing by the origin server, before any subsequent GET is received.1427 A successfulresponse only implies that the user agent's intent was achieved at the time of its processing by the origin server.1422 <p id="rfc.section.7.6.p.1">The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation 1423 enclosed in the request message payload. A successful PUT of a given representation would suggest that a subsequent GET on 1424 that same target resource will result in an equivalent representation being returned in a 200 (OK) response. However, there 1425 is no guarantee that such a state change will be observable, since the target resource might be acted upon by other user agents 1426 in parallel, or might be subject to dynamic processing by the origin server, before any subsequent GET is received. A successful 1427 response only implies that the user agent's intent was achieved at the time of its processing by the origin server. 1428 1428 </p> 1429 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 … … 1494 1494 <div id="rfc.iref.t.1"></div> 1495 1495 <div id="rfc.iref.m.7"></div> 1496 <p id="rfc.section.7.8.p.1">The TRACE method is used to invoke a remote, application-layer loop-back of the request message. The final recipient of the 1497 request <em class="bcp14">SHOULD</em> reflect the message received back to the client as the message-body of a 200 (OK) response. The final recipient is either 1496 <p id="rfc.section.7.8.p.1">The TRACE method requests a remote, application-layer loop-back of the request message. The final recipient of the request <em class="bcp14">SHOULD</em> reflect the message received back to the client as the message-body of a 200 (OK) response. The final recipient is either 1498 1497 the origin server or the first proxy or gateway to receive a Max-Forwards value of zero (0) in the request (see <a href="#header.max-forwards" id="rfc.xref.header.max-forwards.3" title="Max-Forwards">Section 9.5</a>). A TRACE request <em class="bcp14">MUST NOT</em> include a message-body. 1499 1498 </p> … … 1508 1507 <div id="rfc.iref.m.8"></div> 1509 1508 <h2 id="rfc.section.7.9"><a href="#rfc.section.7.9">7.9</a> <a id="CONNECT" href="#CONNECT">CONNECT</a></h2> 1510 <p id="rfc.section.7.9.p.1">The CONNECT method is used with a proxy to dynamically switch the connection to a tunnel.</p> 1511 <p id="rfc.section.7.9.p.2">When using CONNECT, the request-target <em class="bcp14">MUST</em> be use the authority form (<a href="p1-messaging.html#request-target" title="request-target">Section 4.1.2</a> of <a href="#Part1" id="rfc.xref.Part1.26"><cite title="HTTP/1.1, part 1: URIs, Connections, and Message Parsing">[Part1]</cite></a>); i.e., the host name and port number destination of the requested connection separated by a colon: 1509 <p id="rfc.section.7.9.p.1">The CONNECT method requests that the proxy establish a tunnel to the request-target and then restrict its behavior to blind 1510 forwarding of packets until the connection is closed. 1511 </p> 1512 <p id="rfc.section.7.9.p.2">When using CONNECT, the request-target <em class="bcp14">MUST</em> use the authority form (<a href="p1-messaging.html#request-target" title="request-target">Section 4.1.2</a> of <a href="#Part1" id="rfc.xref.Part1.26"><cite title="HTTP/1.1, part 1: URIs, Connections, and Message Parsing">[Part1]</cite></a>); i.e., the request-target consists of only the host name and port number of the tunnel destination, separated by a colon. 1513 For example, 1512 1514 </p> 1513 1515 <div id="rfc.figure.u.10"></div><pre class="text2">CONNECT server.example.com:80 HTTP/1.1 … … 1890 1892 <div id="rfc.iref.s.34"></div> 1891 1893 <h3 id="rfc.section.8.4.16"><a href="#rfc.section.8.4.16">8.4.16</a> <a id="status.415" href="#status.415">415 Unsupported Media Type</a></h3> 1892 <p id="rfc.section.8.4.16.p.1">The server is refusing to service the request because the re presentation of the request is in a format not supported by the1893 target resource for the requested method.1894 <p id="rfc.section.8.4.16.p.1">The server is refusing to service the request because the request payload is in a format not supported by this request method 1895 on the target resource. 1894 1896 </p> 1895 1897 <div id="rfc.iref.55"></div> … … 1972 1974 <h2 id="rfc.section.9.1"><a href="#rfc.section.9.1">9.1</a> <a id="header.allow" href="#header.allow">Allow</a></h2> 1973 1975 <p id="rfc.section.9.1.p.1">The "Allow" response-header field lists the set of methods advertised as supported by the target resource. The purpose of 1974 this field is strictly to inform the recipient of valid methods associated with the resource.1976 this field is strictly to inform the recipient of valid request methods associated with the resource. 1975 1977 </p> 1976 1978 <div id="rfc.figure.u.13"></div><pre class="inline"><span id="rfc.iref.g.6"></span><span id="rfc.iref.g.7"></span> <a href="#header.allow" class="smpl">Allow</a> = "Allow" ":" <a href="#core.rules" class="smpl">OWS</a> <a href="#header.allow" class="smpl">Allow-v</a> … … 2073 2075 <p id="rfc.section.9.5.p.4">Each proxy or gateway recipient of a TRACE or OPTIONS request containing a Max-Forwards header field <em class="bcp14">MUST</em> check and update its value prior to forwarding the request. If the received value is zero (0), the recipient <em class="bcp14">MUST NOT</em> forward the request; instead, it <em class="bcp14">MUST</em> respond as the final recipient. If the received Max-Forwards value is greater than zero, then the forwarded message <em class="bcp14">MUST</em> contain an updated Max-Forwards field with a value decremented by one (1). 2074 2076 </p> 2075 <p id="rfc.section.9.5.p.5">The Max-Forwards header field <em class="bcp14">MAY</em> be ignored for all other methods.2077 <p id="rfc.section.9.5.p.5">The Max-Forwards header field <em class="bcp14">MAY</em> be ignored for all other request methods. 2076 2078 </p> 2077 2079 <div id="rfc.iref.r.1"></div> … … 2158 2160 </pre><h1 id="rfc.section.10"><a href="#rfc.section.10">10.</a> <a id="IANA.considerations" href="#IANA.considerations">IANA Considerations</a></h1> 2159 2161 <h2 id="rfc.section.10.1"><a href="#rfc.section.10.1">10.1</a> <a id="method.registration" href="#method.registration">Method Registry</a></h2> 2160 <p id="rfc.section.10.1.p.1">The registration procedure for HTTP Methods is defined by <a href="#method.registry" title="Method Registry">Section 2.2</a> of this document.2162 <p id="rfc.section.10.1.p.1">The registration procedure for HTTP request methods is defined by <a href="#method.registry" title="Method Registry">Section 2.2</a> of this document. 2161 2163 </p> 2162 2164 <p id="rfc.section.10.1.p.2">The HTTP Method Registry shall be created at <<a href="http://www.iana.org/assignments/http-methods">http://www.iana.org/assignments/http-methods</a>> and be populated with the registrations below: … … 2582 2584 to uniquely identify the user. 2583 2585 </p> 2584 <p id="rfc.section.11.1.p.9">Some methods, like TRACE (<a href="#TRACE" id="rfc.xref.TRACE.4" title="TRACE">Section 7.8</a>), expose information that was sent in request header fields within the body of their response. Clients <em class="bcp14">SHOULD</em> be careful with sensitive information, like Cookies, Authorization credentialsand other header fields that might be used2586 <p id="rfc.section.11.1.p.9">Some request methods, like TRACE (<a href="#TRACE" id="rfc.xref.TRACE.4" title="TRACE">Section 7.8</a>), expose information that was sent in request header fields within the body of their response. Clients <em class="bcp14">SHOULD</em> be careful with sensitive information, like Cookies, Authorization credentials, and other header fields that might be used 2585 2587 to collect data from the client. 2586 2588 </p>
Note: See TracChangeset
for help on using the changeset viewer.