Ignore:
Timestamp:
Mar 26, 2012, 7:44:27 AM (7 years ago)
Author:
julian.reschke@…
Message:

re-org sections

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r1618 r1619  
    311311</section>
    312312
    313 <section title="Method" anchor="method">
     313<section title="Methods" anchor="methods">
    314314  <x:anchor-alias value="method"/>
    315   <x:anchor-alias value="extension-method"/>
    316315<t>
    317316   The method token indicates the request method to be performed on the target
    … …  
    336335</t>
    337336
    338 <section title="Overview of Methods" anchor="overview.of.methods">
    339 <t>
    340   The methods listed below are defined in <xref target="method.definitions"/>.
    341 </t>
    342 <texttable align="left">
    343   <ttcol>Method Name</ttcol><ttcol>Defined in...</ttcol>
    344  
    345   <c>OPTIONS</c> <c><xref target="OPTIONS"/></c>
    346   <c>GET</c> <c><xref target="GET"/></c>
    347   <c>HEAD</c> <c><xref target="HEAD"/></c>
    348   <c>POST</c> <c><xref target="POST"/></c>
    349   <c>PUT</c> <c><xref target="PUT"/></c>
    350   <c>DELETE</c> <c><xref target="DELETE"/></c>
    351   <c>TRACE</c> <c><xref target="TRACE"/></c>
    352   <c>CONNECT</c> <c><xref target="CONNECT"/></c>
    353 </texttable>
    354 <t>
    355   Note that this list is not exhaustive &mdash; it does not include request methods defined
    356   in other specifications.
    357 </t>
     337<section title="Safe and Idempotent Methods" anchor="safe.and.idempotent">
     338
     339<section title="Safe Methods" anchor="safe.methods">
     340<iref item="Safe Methods" primary="true"/>
     341<t>
     342   Implementors need to be aware that the software represents the user in
     343   their interactions over the Internet, and need to allow
     344   the user to be aware of any actions they take which might have an
     345   unexpected significance to themselves or others.
     346</t>
     347<t>
     348   In particular, the convention has been established that the GET, HEAD,
     349   OPTIONS, and TRACE request methods &SHOULD-NOT; have the significance
     350   of taking an action other than retrieval. These request methods ought
     351   to be considered "<x:dfn anchor="safe">safe</x:dfn>".
     352   This allows user agents to represent other methods, such as POST, PUT
     353   and DELETE, in a special way, so that the user is made aware of the
     354   fact that a possibly unsafe action is being requested.
     355</t>
     356<t>
     357   Naturally, it is not possible to ensure that the server does not
     358   generate side-effects as a result of performing a GET request; in
     359   fact, some dynamic resources consider that a feature. The important
     360   distinction here is that the user did not request the side-effects,
     361   so therefore cannot be held accountable for them.
     362</t>
     363</section>
     364
     365<section title="Idempotent Methods" anchor="idempotent.methods">
     366<iref item="Idempotent Methods" primary="true"/>
     367<t>
     368   Request methods can also have the property of "idempotence" in that,
     369   aside from error or expiration issues, the intended effect of multiple
     370   identical requests is the same as for a single request.
     371   PUT, DELETE, and all safe request methods are idempotent.
     372   It is important to note that idempotence refers only to changes
     373   requested by the client: a server is free to change its state due
     374   to multiple requests for the purpose of tracking those requests,
     375   versioning of results, etc.
     376</t>
     377</section>
    358378</section>
    359379
    … …  
    366386  Registrations &MUST; include the following fields:
    367387  <list style="symbols">
    368     <t>Method Name (see <xref target="method"/>)</t>
     388    <t>Method Name (see <xref target="methods"/>)</t>
    369389    <t>Safe ("yes" or "no", see <xref target="safe.methods"/>)</t>
    370390    <t>Pointer to specification text</t>
    … …  
    409429</t>
    410430</section>
    411 
    412 </section>
     431</section>
     432
     433<section title="Method Definitions" anchor="method.definitions">
     434
     435<section title="OPTIONS" anchor="OPTIONS">
     436  <rdf:Description>
     437    <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
     438  </rdf:Description>
     439  <iref primary="true" item="OPTIONS method" x:for-anchor=""/>
     440  <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/>
     441<t>
     442   The OPTIONS method requests information about the
     443   communication options available on the request/response chain
     444   identified by the effective request URI. This method allows a client to
     445   determine the options and/or requirements associated with a resource,
     446   or the capabilities of a server, without implying a resource action
     447   or initiating a resource retrieval.
     448</t>
     449<t>
     450   Responses to the OPTIONS method are not cacheable.
     451</t>
     452<t>
     453   If the OPTIONS request includes a message body (as indicated by the
     454   presence of Content-Length or Transfer-Encoding), then the media type
     455   &MUST; be indicated by a Content-Type field. Although this
     456   specification does not define any use for such a body, future
     457   extensions to HTTP might use the OPTIONS body to make more detailed
     458   queries on the server.
     459</t>
     460<t>
     461   If the request-target (&request-target;) is an asterisk ("*"),
     462   the OPTIONS request is
     463   intended to apply to the server in general rather than to a specific
     464   resource. Since a server's communication options typically depend on
     465   the resource, the "*" request is only useful as a "ping" or "no-op"
     466   type of method; it does nothing beyond allowing the client to test
     467   the capabilities of the server. For example, this can be used to test
     468   a proxy for HTTP/1.1 conformance (or lack thereof).
     469</t>
     470<t>
     471   If the request-target is not an asterisk, the OPTIONS request applies
     472   only to the options that are available when communicating with that
     473   resource.
     474</t>
     475<t>
     476   A 200 response &SHOULD; include any header fields that indicate
     477   optional features implemented by the server and applicable to that
     478   resource (e.g., Allow), possibly including extensions not defined by
     479   this specification. The response body, if any, &SHOULD; also include
     480   information about the communication options. The format for such a
     481   body is not defined by this specification, but might be defined by
     482   future extensions to HTTP. Content negotiation &MAY; be used to select
     483   the appropriate response format. If no response body is included, the
     484   response &MUST; include a Content-Length field with a field-value of
     485   "0".
     486</t>
     487<t>
     488   The Max-Forwards header field &MAY; be used to target a
     489   specific proxy in the request chain (see <xref target="header.max-forwards"/>).
     490   If no Max-Forwards field is present in the request, then the forwarded
     491   request &MUST-NOT; include a Max-Forwards field.
     492</t>
     493</section>
     494
     495<section title="GET" anchor="GET">
     496  <rdf:Description>
     497    <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
     498  </rdf:Description>
     499  <iref primary="true" item="GET method" x:for-anchor=""/>
     500  <iref primary="true" item="Methods" subitem="GET" x:for-anchor=""/>
     501<t>
     502   The GET method requests transfer of a current representation of
     503   the target resource.
     504</t>
     505<t>   
     506   If the target resource is a data-producing process, it is the
     507   produced data which shall be returned as the representation in the response and not
     508   the source text of the process, unless that text happens to be the output of
     509   the process.
     510</t>
     511<t>
     512   The semantics of the GET method change to a "conditional GET" if the
     513   request message includes an If-Modified-Since, If-Unmodified-Since,
     514   If-Match, If-None-Match, or If-Range header field. A conditional GET
     515   requests that the representation be transferred only under the
     516   circumstances described by the conditional header field(s). The
     517   conditional GET request is intended to reduce unnecessary network
     518   usage by allowing cached representations to be refreshed without requiring
     519   multiple requests or transferring data already held by the client.
     520</t>
     521<t>
     522   The semantics of the GET method change to a "partial GET" if the
     523   request message includes a Range header field. A partial GET requests
     524   that only part of the representation be transferred, as described in &header-range;.
     525   The partial GET request is intended to reduce unnecessary
     526   network usage by allowing partially-retrieved representations to be
     527   completed without transferring data already held by the client.
     528</t>
     529<t>
     530   Bodies on GET requests have no defined semantics. Note that sending a body
     531   on a GET request might cause some existing implementations to reject the
     532   request.
     533</t>
     534<t>
     535   The response to a GET request is cacheable and &MAY; be used to satisfy
     536   subsequent GET and HEAD requests (see &caching;).
     537</t>
     538<t>
     539   See <xref target="encoding.sensitive.information.in.uris"/> for security considerations when used for forms.
     540</t>
     541</section>
     542
     543<section title="HEAD" anchor="HEAD">
     544  <rdf:Description>
     545    <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
     546  </rdf:Description>
     547  <iref primary="true" item="HEAD method" x:for-anchor=""/>
     548  <iref primary="true" item="Methods" subitem="HEAD" x:for-anchor=""/>
     549<t>
     550   The HEAD method is identical to GET except that the server &MUST-NOT;
     551   return a message body in the response. The metadata contained
     552   in the HTTP header fields in response to a HEAD request &SHOULD; be identical
     553   to the information sent in response to a GET request. This method can
     554   be used for obtaining metadata about the representation implied by the
     555   request without transferring the representation body. This method is
     556   often used for testing hypertext links for validity, accessibility,
     557   and recent modification.
     558</t>
     559<t>
     560   The response to a HEAD request is cacheable and &MAY; be used to satisfy
     561   a subsequent HEAD request. It also has potential side effects on
     562   previously stored responses to GET; see &p6-head;.
     563</t>
     564<t>
     565   Bodies on HEAD requests have no defined semantics. Note that sending a body
     566   on a HEAD request might cause some existing implementations to reject the
     567   request.
     568</t>
     569</section>
     570
     571<section title="POST" anchor="POST">
     572  <iref primary="true" item="POST method" x:for-anchor=""/>
     573  <iref primary="true" item="Methods" subitem="POST" x:for-anchor=""/>
     574<t>
     575   The POST method requests that the origin server accept the
     576   representation enclosed in the request as data to be processed by the
     577   target resource. POST is designed to allow a uniform method to cover the
     578   following functions:
     579  <list style="symbols">
     580    <t>
     581      Annotation of existing resources;
     582    </t>
     583    <t>
     584        Posting a message to a bulletin board, newsgroup, mailing list,
     585        or similar group of articles;
     586    </t>
     587    <t>
     588        Providing a block of data, such as the result of submitting a
     589        form, to a data-handling process;
     590    </t>
     591    <t>
     592        Extending a database through an append operation.
     593    </t>
     594  </list>
     595</t>
     596<t>
     597   The actual function performed by the POST method is determined by the
     598   server and is usually dependent on the effective request URI.
     599</t>
     600<t>
     601   The action performed by the POST method might not result in a
     602   resource that can be identified by a URI. In this case, either 200
     603   (OK) or 204 (No Content) is the appropriate response status code,
     604   depending on whether or not the response includes a representation that
     605   describes the result.
     606</t>
     607<t>
     608   If a resource has been created on the origin server, the response
     609   &SHOULD; be 201 (Created) and contain a representation which describes the
     610   status of the request and refers to the new resource, and a Location
     611   header field (see <xref target="header.location"/>).
     612</t>
     613<t>
     614   Responses to POST requests are only cacheable when they
     615   include explicit freshness information (see &p6-explicit;). A
     616   cached POST response with a Content-Location header field
     617   (see &header-content-location;) whose value is the effective
     618   Request URI &MAY; be used to satisfy subsequent GET and HEAD requests.
     619</t>
     620<t>
     621   Note that POST caching is not widely implemented.
     622   However, the 303 (See Other) response can be used to direct the
     623   user agent to retrieve a cacheable representation of the resource.
     624</t>
     625</section>
     626
     627<section title="PUT" anchor="PUT">
     628  <iref primary="true" item="PUT method" x:for-anchor=""/>
     629  <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/>
     630<t>
     631   The PUT method requests that the state of the target resource
     632   be created or replaced with the state defined by the representation
     633   enclosed in the request message payload.  A successful PUT of a given
     634   representation would suggest that a subsequent GET on that same target
     635   resource will result in an equivalent representation being returned in
     636   a 200 (OK) response.  However, there is no guarantee that such a state
     637   change will be observable, since the target resource might be acted
     638   upon by other user agents in parallel, or might be subject to dynamic
     639   processing by the origin server, before any subsequent GET is received.
     640   A successful response only implies that the user agent's intent was
     641   achieved at the time of its processing by the origin server.
     642</t>
     643<t>   
     644   If the target resource does not have a current representation and
     645   the PUT successfully creates one, then the origin server &MUST; inform
     646   the user agent by sending a 201 (Created) response.  If the target
     647   resource does have a current representation and that representation is
     648   successfully modified in accordance with the state of the enclosed
     649   representation, then either a 200 (OK) or 204 (No Content) response
     650   &SHOULD; be sent to indicate successful completion of the request.
     651</t>
     652<t>
     653   Unrecognized header fields &SHOULD; be ignored (i.e., not saved
     654   as part of the resource state).
     655</t>
     656<t>
     657   An origin server &SHOULD; verify that the PUT representation is
     658   consistent with any constraints which the server has for the target
     659   resource that cannot or will not be changed by the PUT.  This is
     660   particularly important when the origin server uses internal
     661   configuration information related to the URI in order to set the
     662   values for representation metadata on GET responses.  When a PUT
     663   representation is inconsistent with the target resource, the origin
     664   server &SHOULD; either make them consistent, by transforming the
     665   representation or changing the resource configuration, or respond
     666   with an appropriate error message containing sufficient information
     667   to explain why the representation is unsuitable.  The 409 (Conflict)
     668   or 415 (Unsupported Media Type) status codes are suggested, with the
     669   latter being specific to constraints on Content-Type values.
     670</t>
     671<t>
     672   For example, if the target resource is configured to always have a
     673   Content-Type of "text/html" and the representation being PUT has a
     674   Content-Type of "image/jpeg", then the origin server &SHOULD; do one of:
     675   (a) reconfigure the target resource to reflect the new media type;
     676   (b) transform the PUT representation to a format consistent with that
     677   of the resource before saving it as the new resource state; or,
     678   (c) reject the request with a 415 response indicating that the target
     679   resource is limited to "text/html", perhaps including a link to a
     680   different resource that would be a suitable target for the new
     681   representation.
     682</t>
     683<t>
     684   HTTP does not define exactly how a PUT method affects the state
     685   of an origin server beyond what can be expressed by the intent of
     686   the user agent request and the semantics of the origin server response.
     687   It does not define what a resource might be, in any sense of that
     688   word, beyond the interface provided via HTTP.  It does not define
     689   how resource state is "stored", nor how such storage might change
     690   as a result of a change in resource state, nor how the origin server
     691   translates resource state into representations.  Generally speaking,
     692   all implementation details behind the resource interface are
     693   intentionally hidden by the server.
     694</t>
     695<t>
     696   The fundamental difference between the POST and PUT methods is
     697   highlighted by the different intent for the target resource.
     698   The target resource in a POST request is intended to handle the
     699   enclosed representation as a data-accepting process, such as for
     700   a gateway to some other protocol or a document that accepts annotations.
     701   In contrast, the target resource in a PUT request is intended to
     702   take the enclosed representation as a new or replacement value.
     703   Hence, the intent of PUT is idempotent and visible to intermediaries,
     704   even though the exact effect is only known by the origin server.
     705</t>
     706<t>
     707   Proper interpretation of a PUT request presumes that the user agent
     708   knows what target resource is desired.  A service that is intended
     709   to select a proper URI on behalf of the client, after receiving
     710   a state-changing request, &SHOULD; be implemented using the POST
     711   method rather than PUT.  If the origin server will not make the
     712   requested PUT state change to the target resource and instead
     713   wishes to have it applied to a different resource, such as when the
     714   resource has been moved to a different URI, then the origin server
     715   &MUST; send a 301 (Moved Permanently) response; the user agent &MAY;
     716   then make its own decision regarding whether or not to redirect the
     717   request.
     718</t>
     719<t>
     720   A PUT request applied to the target resource &MAY; have side-effects
     721   on other resources.  For example, an article might have a URI for
     722   identifying "the current version" (a resource) which is separate
     723   from the URIs identifying each particular version (different
     724   resources that at one point shared the same state as the current version
     725   resource).  A successful PUT request on "the current version" URI might
     726   therefore create a new version resource in addition to changing the
     727   state of the target resource, and might also cause links to be added
     728   between the related resources.
     729</t>
     730<t>
     731   An origin server &SHOULD; reject any PUT request that contains a
     732   Content-Range header field, since it might be misinterpreted as
     733   partial content (or might be partial content that is being mistakenly
     734   PUT as a full representation).  Partial content updates are
     735   possible by targeting a separately identified resource with state
     736   that overlaps a portion of the larger resource, or by using a
     737   different method that has been specifically defined for partial
     738   updates (for example, the PATCH method defined in
     739   <xref target="RFC5789"/>).
     740</t>
     741<t>
     742   Responses to the PUT method are not cacheable. If a PUT request passes
     743   through a cache that has one or more stored responses for the effective
     744   request URI, those stored responses will be invalidated (see
     745   &p6-invalid;).
     746</t>
     747</section>
     748
     749<section title="DELETE" anchor="DELETE">
     750  <iref primary="true" item="DELETE method" x:for-anchor=""/>
     751  <iref primary="true" item="Methods" subitem="DELETE" x:for-anchor=""/>
     752<t>
     753   The DELETE method requests that the origin server delete the target
     754   resource. This method &MAY; be overridden by
     755   human intervention (or other means) on the origin server. The client cannot
     756   be guaranteed that the operation has been carried out, even if the
     757   status code returned from the origin server indicates that the action
     758   has been completed successfully. However, the server &SHOULD-NOT;
     759   indicate success unless, at the time the response is given, it
     760   intends to delete the resource or move it to an inaccessible
     761   location.
     762</t>
     763<t>
     764   A successful response &SHOULD; be 200 (OK) if the response includes an
     765   representation describing the status, 202 (Accepted) if the action has not
     766   yet been enacted, or 204 (No Content) if the action has been enacted
     767   but the response does not include a representation.
     768</t>
     769<t>
     770   Bodies on DELETE requests have no defined semantics. Note that sending a body
     771   on a DELETE request might cause some existing implementations to reject the
     772   request.
     773</t>
     774<t>
     775   Responses to the DELETE method are not cacheable. If a DELETE request
     776   passes through a cache that has one or more stored responses for the
     777   effective request URI, those stored responses will be invalidated (see
     778   &p6-invalid;).
     779</t>
     780</section>
     781
     782<section title="TRACE" anchor="TRACE">
     783  <rdf:Description>
     784    <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
     785  </rdf:Description>
     786  <iref primary="true" item="TRACE method" x:for-anchor=""/>
     787  <iref primary="true" item="Methods" subitem="TRACE" x:for-anchor=""/>
     788<t>
     789   The TRACE method requests a remote, application-layer loop-back
     790   of the request message. The final recipient of the request
     791   &SHOULD; reflect the message received back to the client as the
     792   message body of a 200 (OK) response. The final recipient is either the
     793   origin server or the first proxy to receive a Max-Forwards
     794   value of zero (0) in the request (see <xref target="header.max-forwards"/>).
     795   A TRACE request &MUST-NOT; include a message body.
     796</t>
     797<t>
     798   TRACE allows the client to see what is being received at the other
     799   end of the request chain and use that data for testing or diagnostic
     800   information. The value of the Via header field (&header-via;) is of
     801   particular interest, since it acts as a trace of the request chain.
     802   Use of the Max-Forwards header field allows the client to limit the
     803   length of the request chain, which is useful for testing a chain of
     804   proxies forwarding messages in an infinite loop.
     805</t>
     806<t>
     807   If the request is valid, the response &SHOULD; have a Content-Type of
     808   "message/http" (see &media-type-message-http;) and contain a message body
     809   that encloses a copy of the entire request message.
     810   Responses to the TRACE method are not cacheable.
     811</t>
     812</section>
     813
     814<section title="CONNECT" anchor="CONNECT">
     815  <iref primary="true" item="CONNECT method" x:for-anchor=""/>
     816  <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/>
     817<t>
     818   The CONNECT method requests that the proxy establish a tunnel
     819   to the request-target and, if successful, thereafter restrict its behavior
     820   to blind forwarding of packets until the connection is closed.
     821</t>
     822<t>
     823   When using CONNECT, the request-target &MUST; use the authority form
     824   (&request-target;); i.e., the request-target consists of only the
     825   host name and port number of the tunnel destination, separated by a colon.
     826   For example,
     827</t>
     828<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
     829CONNECT server.example.com:80 HTTP/1.1
     830Host: server.example.com:80
     831
     832</artwork></figure>
     833<t>
     834   Any successful (2xx) response to a CONNECT request indicates that the
     835   proxy has established a connection to the requested host and port,
     836   and has switched to tunneling the current connection to that server
     837   connection.
     838   The tunneled data from the server begins immediately after the blank line
     839   that concludes the successful response's header block.
     840   A server &SHOULD-NOT; send any Transfer-Encoding or Content-Length
     841   header fields in a successful response.
     842   A client &MUST; ignore any Content-Length or Transfer-Encoding header
     843   fields received in a successful response.
     844</t>
     845<t>
     846   Any response other than a successful response indicates that the tunnel
     847   has not yet been formed and that the connection remains governed by HTTP.
     848</t>
     849<t>
     850   Proxy authentication might be used to establish the
     851   authority to create a tunnel:
     852</t>
     853<figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
     854CONNECT server.example.com:80 HTTP/1.1
     855Host: server.example.com:80
     856Proxy-Authorization: basic aGVsbG86d29ybGQ=
     857
     858</artwork></figure>
     859<t>
     860   A message body on a CONNECT request has no defined semantics. Sending a
     861   body on a CONNECT request might cause existing implementations to reject
     862   the request.
     863</t>
     864<t>
     865   Similar to a pipelined HTTP/1.1 request, data to be tunneled from client
     866   to server &MAY; be sent immediately after the request (before a response
     867   is received). The usual caveats also apply:
     868   data may be discarded if the eventual response is negative, and the
     869   connection may be reset with no response if more than one TCP segment
     870   is outstanding.
     871</t>
     872<t>
     873   It may be the case that the proxy itself can only reach the requested
     874   origin server through another proxy.  In this case, the first proxy
     875   &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel
     876   to the authority.  A proxy &MUST-NOT; respond with any 2xx status code
     877   unless it has either a direct or tunnel connection established to the
     878   authority.
     879</t>
     880<t>
     881   If at any point either one of the peers gets disconnected, any
     882   outstanding data that came from that peer will be passed to the other
     883   one, and after that also the other connection will be terminated by
     884   the proxy. If there is outstanding data to that peer undelivered,
     885   that data will be discarded.
     886</t>
     887<t>
     888   An origin server which receives a CONNECT request for itself &MAY;
     889   respond with a 2xx status code to indicate that a connection is
     890   established.  However, most origin servers do not implement CONNECT.
     891</t>
     892</section>
     893</section>
     894
    413895</section>
    414896
    … …  
    16362118
    16372119
    1638 <section title="Method Definitions" anchor="method.definitions">
    1639 <t>
    1640    The set of common request methods for HTTP/1.1 is defined below. Although
    1641    this set can be expanded, additional methods cannot be assumed to
    1642    share the same semantics for separately extended clients and servers.
    1643 </t>
    1644 
    1645 <section title="Safe and Idempotent Methods" anchor="safe.and.idempotent">
    1646 
    1647 <section title="Safe Methods" anchor="safe.methods">
    1648 <iref item="Safe Methods" primary="true"/>
    1649 <t>
    1650    Implementors need to be aware that the software represents the user in
    1651    their interactions over the Internet, and need to allow
    1652    the user to be aware of any actions they take which might have an
    1653    unexpected significance to themselves or others.
    1654 </t>
    1655 <t>
    1656    In particular, the convention has been established that the GET, HEAD,
    1657    OPTIONS, and TRACE request methods &SHOULD-NOT; have the significance
    1658    of taking an action other than retrieval. These request methods ought
    1659    to be considered "<x:dfn anchor="safe">safe</x:dfn>".
    1660    This allows user agents to represent other methods, such as POST, PUT
    1661    and DELETE, in a special way, so that the user is made aware of the
    1662    fact that a possibly unsafe action is being requested.
    1663 </t>
    1664 <t>
    1665    Naturally, it is not possible to ensure that the server does not
    1666    generate side-effects as a result of performing a GET request; in
    1667    fact, some dynamic resources consider that a feature. The important
    1668    distinction here is that the user did not request the side-effects,
    1669    so therefore cannot be held accountable for them.
    1670 </t>
    1671 </section>
    1672 
    1673 <section title="Idempotent Methods" anchor="idempotent.methods">
    1674 <iref item="Idempotent Methods" primary="true"/>
    1675 <t>
    1676    Request methods can also have the property of "idempotence" in that,
    1677    aside from error or expiration issues, the intended effect of multiple
    1678    identical requests is the same as for a single request.
    1679    PUT, DELETE, and all safe request methods are idempotent.
    1680    It is important to note that idempotence refers only to changes
    1681    requested by the client: a server is free to change its state due
    1682    to multiple requests for the purpose of tracking those requests,
    1683    versioning of results, etc.
    1684 </t>
    1685 </section>
    1686 </section>
    1687 
    1688 <section title="OPTIONS" anchor="OPTIONS">
    1689   <rdf:Description>
    1690     <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
    1691   </rdf:Description>
    1692   <iref primary="true" item="OPTIONS method" x:for-anchor=""/>
    1693   <iref primary="true" item="Methods" subitem="OPTIONS" x:for-anchor=""/>
    1694 <t>
    1695    The OPTIONS method requests information about the
    1696    communication options available on the request/response chain
    1697    identified by the effective request URI. This method allows a client to
    1698    determine the options and/or requirements associated with a resource,
    1699    or the capabilities of a server, without implying a resource action
    1700    or initiating a resource retrieval.
    1701 </t>
    1702 <t>
    1703    Responses to the OPTIONS method are not cacheable.
    1704 </t>
    1705 <t>
    1706    If the OPTIONS request includes a message body (as indicated by the
    1707    presence of Content-Length or Transfer-Encoding), then the media type
    1708    &MUST; be indicated by a Content-Type field. Although this
    1709    specification does not define any use for such a body, future
    1710    extensions to HTTP might use the OPTIONS body to make more detailed
    1711    queries on the server.
    1712 </t>
    1713 <t>
    1714    If the request-target (&request-target;) is an asterisk ("*"),
    1715    the OPTIONS request is
    1716    intended to apply to the server in general rather than to a specific
    1717    resource. Since a server's communication options typically depend on
    1718    the resource, the "*" request is only useful as a "ping" or "no-op"
    1719    type of method; it does nothing beyond allowing the client to test
    1720    the capabilities of the server. For example, this can be used to test
    1721    a proxy for HTTP/1.1 conformance (or lack thereof).
    1722 </t>
    1723 <t>
    1724    If the request-target is not an asterisk, the OPTIONS request applies
    1725    only to the options that are available when communicating with that
    1726    resource.
    1727 </t>
    1728 <t>
    1729    A 200 response &SHOULD; include any header fields that indicate
    1730    optional features implemented by the server and applicable to that
    1731    resource (e.g., Allow), possibly including extensions not defined by
    1732    this specification. The response body, if any, &SHOULD; also include
    1733    information about the communication options. The format for such a
    1734    body is not defined by this specification, but might be defined by
    1735    future extensions to HTTP. Content negotiation &MAY; be used to select
    1736    the appropriate response format. If no response body is included, the
    1737    response &MUST; include a Content-Length field with a field-value of
    1738    "0".
    1739 </t>
    1740 <t>
    1741    The Max-Forwards header field &MAY; be used to target a
    1742    specific proxy in the request chain (see <xref target="header.max-forwards"/>).
    1743    If no Max-Forwards field is present in the request, then the forwarded
    1744    request &MUST-NOT; include a Max-Forwards field.
    1745 </t>
    1746 </section>
    1747 
    1748 <section title="GET" anchor="GET">
    1749   <rdf:Description>
    1750     <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
    1751   </rdf:Description>
    1752   <iref primary="true" item="GET method" x:for-anchor=""/>
    1753   <iref primary="true" item="Methods" subitem="GET" x:for-anchor=""/>
    1754 <t>
    1755    The GET method requests transfer of a current representation of
    1756    the target resource.
    1757 </t>
    1758 <t>   
    1759    If the target resource is a data-producing process, it is the
    1760    produced data which shall be returned as the representation in the response and not
    1761    the source text of the process, unless that text happens to be the output of
    1762    the process.
    1763 </t>
    1764 <t>
    1765    The semantics of the GET method change to a "conditional GET" if the
    1766    request message includes an If-Modified-Since, If-Unmodified-Since,
    1767    If-Match, If-None-Match, or If-Range header field. A conditional GET
    1768    requests that the representation be transferred only under the
    1769    circumstances described by the conditional header field(s). The
    1770    conditional GET request is intended to reduce unnecessary network
    1771    usage by allowing cached representations to be refreshed without requiring
    1772    multiple requests or transferring data already held by the client.
    1773 </t>
    1774 <t>
    1775    The semantics of the GET method change to a "partial GET" if the
    1776    request message includes a Range header field. A partial GET requests
    1777    that only part of the representation be transferred, as described in &header-range;.
    1778    The partial GET request is intended to reduce unnecessary
    1779    network usage by allowing partially-retrieved representations to be
    1780    completed without transferring data already held by the client.
    1781 </t>
    1782 <t>
    1783    Bodies on GET requests have no defined semantics. Note that sending a body
    1784    on a GET request might cause some existing implementations to reject the
    1785    request.
    1786 </t>
    1787 <t>
    1788    The response to a GET request is cacheable and &MAY; be used to satisfy
    1789    subsequent GET and HEAD requests (see &caching;).
    1790 </t>
    1791 <t>
    1792    See <xref target="encoding.sensitive.information.in.uris"/> for security considerations when used for forms.
    1793 </t>
    1794 </section>
    1795 
    1796 <section title="HEAD" anchor="HEAD">
    1797   <rdf:Description>
    1798     <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
    1799   </rdf:Description>
    1800   <iref primary="true" item="HEAD method" x:for-anchor=""/>
    1801   <iref primary="true" item="Methods" subitem="HEAD" x:for-anchor=""/>
    1802 <t>
    1803    The HEAD method is identical to GET except that the server &MUST-NOT;
    1804    return a message body in the response. The metadata contained
    1805    in the HTTP header fields in response to a HEAD request &SHOULD; be identical
    1806    to the information sent in response to a GET request. This method can
    1807    be used for obtaining metadata about the representation implied by the
    1808    request without transferring the representation body. This method is
    1809    often used for testing hypertext links for validity, accessibility,
    1810    and recent modification.
    1811 </t>
    1812 <t>
    1813    The response to a HEAD request is cacheable and &MAY; be used to satisfy
    1814    a subsequent HEAD request. It also has potential side effects on
    1815    previously stored responses to GET; see &p6-head;.
    1816 </t>
    1817 <t>
    1818    Bodies on HEAD requests have no defined semantics. Note that sending a body
    1819    on a HEAD request might cause some existing implementations to reject the
    1820    request.
    1821 </t>
    1822 </section>
    1823 
    1824 <section title="POST" anchor="POST">
    1825   <iref primary="true" item="POST method" x:for-anchor=""/>
    1826   <iref primary="true" item="Methods" subitem="POST" x:for-anchor=""/>
    1827 <t>
    1828    The POST method requests that the origin server accept the
    1829    representation enclosed in the request as data to be processed by the
    1830    target resource. POST is designed to allow a uniform method to cover the
    1831    following functions:
    1832   <list style="symbols">
    1833     <t>
    1834       Annotation of existing resources;
    1835     </t>
    1836     <t>
    1837         Posting a message to a bulletin board, newsgroup, mailing list,
    1838         or similar group of articles;
    1839     </t>
    1840     <t>
    1841         Providing a block of data, such as the result of submitting a
    1842         form, to a data-handling process;
    1843     </t>
    1844     <t>
    1845         Extending a database through an append operation.
    1846     </t>
    1847   </list>
    1848 </t>
    1849 <t>
    1850    The actual function performed by the POST method is determined by the
    1851    server and is usually dependent on the effective request URI.
    1852 </t>
    1853 <t>
    1854    The action performed by the POST method might not result in a
    1855    resource that can be identified by a URI. In this case, either 200
    1856    (OK) or 204 (No Content) is the appropriate response status code,
    1857    depending on whether or not the response includes a representation that
    1858    describes the result.
    1859 </t>
    1860 <t>
    1861    If a resource has been created on the origin server, the response
    1862    &SHOULD; be 201 (Created) and contain a representation which describes the
    1863    status of the request and refers to the new resource, and a Location
    1864    header field (see <xref target="header.location"/>).
    1865 </t>
    1866 <t>
    1867    Responses to POST requests are only cacheable when they
    1868    include explicit freshness information (see &p6-explicit;). A
    1869    cached POST response with a Content-Location header field
    1870    (see &header-content-location;) whose value is the effective
    1871    Request URI &MAY; be used to satisfy subsequent GET and HEAD requests.
    1872 </t>
    1873 <t>
    1874    Note that POST caching is not widely implemented.
    1875    However, the 303 (See Other) response can be used to direct the
    1876    user agent to retrieve a cacheable representation of the resource.
    1877 </t>
    1878 </section>
    1879 
    1880 <section title="PUT" anchor="PUT">
    1881   <iref primary="true" item="PUT method" x:for-anchor=""/>
    1882   <iref primary="true" item="Methods" subitem="PUT" x:for-anchor=""/>
    1883 <t>
    1884    The PUT method requests that the state of the target resource
    1885    be created or replaced with the state defined by the representation
    1886    enclosed in the request message payload.  A successful PUT of a given
    1887    representation would suggest that a subsequent GET on that same target
    1888    resource will result in an equivalent representation being returned in
    1889    a 200 (OK) response.  However, there is no guarantee that such a state
    1890    change will be observable, since the target resource might be acted
    1891    upon by other user agents in parallel, or might be subject to dynamic
    1892    processing by the origin server, before any subsequent GET is received.
    1893    A successful response only implies that the user agent's intent was
    1894    achieved at the time of its processing by the origin server.
    1895 </t>
    1896 <t>   
    1897    If the target resource does not have a current representation and
    1898    the PUT successfully creates one, then the origin server &MUST; inform
    1899    the user agent by sending a 201 (Created) response.  If the target
    1900    resource does have a current representation and that representation is
    1901    successfully modified in accordance with the state of the enclosed
    1902    representation, then either a 200 (OK) or 204 (No Content) response
    1903    &SHOULD; be sent to indicate successful completion of the request.
    1904 </t>
    1905 <t>
    1906    Unrecognized header fields &SHOULD; be ignored (i.e., not saved
    1907    as part of the resource state).
    1908 </t>
    1909 <t>
    1910    An origin server &SHOULD; verify that the PUT representation is
    1911    consistent with any constraints which the server has for the target
    1912    resource that cannot or will not be changed by the PUT.  This is
    1913    particularly important when the origin server uses internal
    1914    configuration information related to the URI in order to set the
    1915    values for representation metadata on GET responses.  When a PUT
    1916    representation is inconsistent with the target resource, the origin
    1917    server &SHOULD; either make them consistent, by transforming the
    1918    representation or changing the resource configuration, or respond
    1919    with an appropriate error message containing sufficient information
    1920    to explain why the representation is unsuitable.  The 409 (Conflict)
    1921    or 415 (Unsupported Media Type) status codes are suggested, with the
    1922    latter being specific to constraints on Content-Type values.
    1923 </t>
    1924 <t>
    1925    For example, if the target resource is configured to always have a
    1926    Content-Type of "text/html" and the representation being PUT has a
    1927    Content-Type of "image/jpeg", then the origin server &SHOULD; do one of:
    1928    (a) reconfigure the target resource to reflect the new media type;
    1929    (b) transform the PUT representation to a format consistent with that
    1930    of the resource before saving it as the new resource state; or,
    1931    (c) reject the request with a 415 response indicating that the target
    1932    resource is limited to "text/html", perhaps including a link to a
    1933    different resource that would be a suitable target for the new
    1934    representation.
    1935 </t>
    1936 <t>
    1937    HTTP does not define exactly how a PUT method affects the state
    1938    of an origin server beyond what can be expressed by the intent of
    1939    the user agent request and the semantics of the origin server response.
    1940    It does not define what a resource might be, in any sense of that
    1941    word, beyond the interface provided via HTTP.  It does not define
    1942    how resource state is "stored", nor how such storage might change
    1943    as a result of a change in resource state, nor how the origin server
    1944    translates resource state into representations.  Generally speaking,
    1945    all implementation details behind the resource interface are
    1946    intentionally hidden by the server.
    1947 </t>
    1948 <t>
    1949    The fundamental difference between the POST and PUT methods is
    1950    highlighted by the different intent for the target resource.
    1951    The target resource in a POST request is intended to handle the
    1952    enclosed representation as a data-accepting process, such as for
    1953    a gateway to some other protocol or a document that accepts annotations.
    1954    In contrast, the target resource in a PUT request is intended to
    1955    take the enclosed representation as a new or replacement value.
    1956    Hence, the intent of PUT is idempotent and visible to intermediaries,
    1957    even though the exact effect is only known by the origin server.
    1958 </t>
    1959 <t>
    1960    Proper interpretation of a PUT request presumes that the user agent
    1961    knows what target resource is desired.  A service that is intended
    1962    to select a proper URI on behalf of the client, after receiving
    1963    a state-changing request, &SHOULD; be implemented using the POST
    1964    method rather than PUT.  If the origin server will not make the
    1965    requested PUT state change to the target resource and instead
    1966    wishes to have it applied to a different resource, such as when the
    1967    resource has been moved to a different URI, then the origin server
    1968    &MUST; send a 301 (Moved Permanently) response; the user agent &MAY;
    1969    then make its own decision regarding whether or not to redirect the
    1970    request.
    1971 </t>
    1972 <t>
    1973    A PUT request applied to the target resource &MAY; have side-effects
    1974    on other resources.  For example, an article might have a URI for
    1975    identifying "the current version" (a resource) which is separate
    1976    from the URIs identifying each particular version (different
    1977    resources that at one point shared the same state as the current version
    1978    resource).  A successful PUT request on "the current version" URI might
    1979    therefore create a new version resource in addition to changing the
    1980    state of the target resource, and might also cause links to be added
    1981    between the related resources.
    1982 </t>
    1983 <t>
    1984    An origin server &SHOULD; reject any PUT request that contains a
    1985    Content-Range header field, since it might be misinterpreted as
    1986    partial content (or might be partial content that is being mistakenly
    1987    PUT as a full representation).  Partial content updates are
    1988    possible by targeting a separately identified resource with state
    1989    that overlaps a portion of the larger resource, or by using a
    1990    different method that has been specifically defined for partial
    1991    updates (for example, the PATCH method defined in
    1992    <xref target="RFC5789"/>).
    1993 </t>
    1994 <t>
    1995    Responses to the PUT method are not cacheable. If a PUT request passes
    1996    through a cache that has one or more stored responses for the effective
    1997    request URI, those stored responses will be invalidated (see
    1998    &p6-invalid;).
    1999 </t>
    2000 </section>
    2001 
    2002 <section title="DELETE" anchor="DELETE">
    2003   <iref primary="true" item="DELETE method" x:for-anchor=""/>
    2004   <iref primary="true" item="Methods" subitem="DELETE" x:for-anchor=""/>
    2005 <t>
    2006    The DELETE method requests that the origin server delete the target
    2007    resource. This method &MAY; be overridden by
    2008    human intervention (or other means) on the origin server. The client cannot
    2009    be guaranteed that the operation has been carried out, even if the
    2010    status code returned from the origin server indicates that the action
    2011    has been completed successfully. However, the server &SHOULD-NOT;
    2012    indicate success unless, at the time the response is given, it
    2013    intends to delete the resource or move it to an inaccessible
    2014    location.
    2015 </t>
    2016 <t>
    2017    A successful response &SHOULD; be 200 (OK) if the response includes an
    2018    representation describing the status, 202 (Accepted) if the action has not
    2019    yet been enacted, or 204 (No Content) if the action has been enacted
    2020    but the response does not include a representation.
    2021 </t>
    2022 <t>
    2023    Bodies on DELETE requests have no defined semantics. Note that sending a body
    2024    on a DELETE request might cause some existing implementations to reject the
    2025    request.
    2026 </t>
    2027 <t>
    2028    Responses to the DELETE method are not cacheable. If a DELETE request
    2029    passes through a cache that has one or more stored responses for the
    2030    effective request URI, those stored responses will be invalidated (see
    2031    &p6-invalid;).
    2032 </t>
    2033 </section>
    2034 
    2035 <section title="TRACE" anchor="TRACE">
    2036   <rdf:Description>
    2037     <safe xmlns="urn:ietf:id:draft-ietf-httpbis-p2-semantics#">yes</safe>
    2038   </rdf:Description>
    2039   <iref primary="true" item="TRACE method" x:for-anchor=""/>
    2040   <iref primary="true" item="Methods" subitem="TRACE" x:for-anchor=""/>
    2041 <t>
    2042    The TRACE method requests a remote, application-layer loop-back
    2043    of the request message. The final recipient of the request
    2044    &SHOULD; reflect the message received back to the client as the
    2045    message body of a 200 (OK) response. The final recipient is either the
    2046    origin server or the first proxy to receive a Max-Forwards
    2047    value of zero (0) in the request (see <xref target="header.max-forwards"/>).
    2048    A TRACE request &MUST-NOT; include a message body.
    2049 </t>
    2050 <t>
    2051    TRACE allows the client to see what is being received at the other
    2052    end of the request chain and use that data for testing or diagnostic
    2053    information. The value of the Via header field (&header-via;) is of
    2054    particular interest, since it acts as a trace of the request chain.
    2055    Use of the Max-Forwards header field allows the client to limit the
    2056    length of the request chain, which is useful for testing a chain of
    2057    proxies forwarding messages in an infinite loop.
    2058 </t>
    2059 <t>
    2060    If the request is valid, the response &SHOULD; have a Content-Type of
    2061    "message/http" (see &media-type-message-http;) and contain a message body
    2062    that encloses a copy of the entire request message.
    2063    Responses to the TRACE method are not cacheable.
    2064 </t>
    2065 </section>
    2066 
    2067 <section title="CONNECT" anchor="CONNECT">
    2068   <iref primary="true" item="CONNECT method" x:for-anchor=""/>
    2069   <iref primary="true" item="Methods" subitem="CONNECT" x:for-anchor=""/>
    2070 <t>
    2071    The CONNECT method requests that the proxy establish a tunnel
    2072    to the request-target and, if successful, thereafter restrict its behavior
    2073    to blind forwarding of packets until the connection is closed.
    2074 </t>
    2075 <t>
    2076    When using CONNECT, the request-target &MUST; use the authority form
    2077    (&request-target;); i.e., the request-target consists of only the
    2078    host name and port number of the tunnel destination, separated by a colon.
    2079    For example,
    2080 </t>
    2081 <figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
    2082 CONNECT server.example.com:80 HTTP/1.1
    2083 Host: server.example.com:80
    2084 
    2085 </artwork></figure>
    2086 <t>
    2087    Any successful (2xx) response to a CONNECT request indicates that the
    2088    proxy has established a connection to the requested host and port,
    2089    and has switched to tunneling the current connection to that server
    2090    connection.
    2091    The tunneled data from the server begins immediately after the blank line
    2092    that concludes the successful response's header block.
    2093    A server &SHOULD-NOT; send any Transfer-Encoding or Content-Length
    2094    header fields in a successful response.
    2095    A client &MUST; ignore any Content-Length or Transfer-Encoding header
    2096    fields received in a successful response.
    2097 </t>
    2098 <t>
    2099    Any response other than a successful response indicates that the tunnel
    2100    has not yet been formed and that the connection remains governed by HTTP.
    2101 </t>
    2102 <t>
    2103    Proxy authentication might be used to establish the
    2104    authority to create a tunnel:
    2105 </t>
    2106 <figure><artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with="  ">
    2107 CONNECT server.example.com:80 HTTP/1.1
    2108 Host: server.example.com:80
    2109 Proxy-Authorization: basic aGVsbG86d29ybGQ=
    2110 
    2111 </artwork></figure>
    2112 <t>
    2113    A message body on a CONNECT request has no defined semantics. Sending a
    2114    body on a CONNECT request might cause existing implementations to reject
    2115    the request.
    2116 </t>
    2117 <t>
    2118    Similar to a pipelined HTTP/1.1 request, data to be tunneled from client
    2119    to server &MAY; be sent immediately after the request (before a response
    2120    is received). The usual caveats also apply:
    2121    data may be discarded if the eventual response is negative, and the
    2122    connection may be reset with no response if more than one TCP segment
    2123    is outstanding.
    2124 </t>
    2125 <t>
    2126    It may be the case that the proxy itself can only reach the requested
    2127    origin server through another proxy.  In this case, the first proxy
    2128    &SHOULD; make a CONNECT request of that next proxy, requesting a tunnel
    2129    to the authority.  A proxy &MUST-NOT; respond with any 2xx status code
    2130    unless it has either a direct or tunnel connection established to the
    2131    authority.
    2132 </t>
    2133 <t>
    2134    If at any point either one of the peers gets disconnected, any
    2135    outstanding data that came from that peer will be passed to the other
    2136    one, and after that also the other connection will be terminated by
    2137    the proxy. If there is outstanding data to that peer undelivered,
    2138    that data will be discarded.
    2139 </t>
    2140 <t>
    2141    An origin server which receives a CONNECT request for itself &MAY;
    2142    respond with a 2xx status code to indicate that a connection is
    2143    established.  However, most origin servers do not implement CONNECT.
    2144 </t>
    2145 </section>
    2146 </section>
    2147 
    21482120<section title="Common Protocol Parameters" anchor="common.protocol.parameters">
    21492121<section title="Date/Time Formats" anchor="http.date">
    … …  
    36793651<section title="Changes from RFC 2616" anchor="changes.from.rfc.2616">
    36803652<t>
     3653  Clarify definition of POST.
     3654  (<xref target="POST"/>)
     3655</t>
     3656<t>
     3657  Remove requirement to handle all Content-* header fields; ban use of
     3658  Content-Range with PUT.
     3659  (<xref target="PUT"/>)
     3660</t>
     3661<t>
     3662  Take over definition of CONNECT method from <xref target="RFC2817"/>.
     3663  (<xref target="CONNECT"/>)
     3664</t>
     3665<t>
    36813666  This document takes over the Status Code Registry, previously defined
    36823667  in <xref target="RFC2817" x:fmt="of" x:sec="7.1"/>.
    … …  
    37143699  <xref target="RFC2817"/>).
    37153700  (<xref target="status.426"/>)
    3716 </t>
    3717 <t>
    3718   Clarify definition of POST.
    3719   (<xref target="POST"/>)
    3720 </t>
    3721 <t>
    3722   Remove requirement to handle all Content-* header fields; ban use of
    3723   Content-Range with PUT.
    3724   (<xref target="PUT"/>)
    3725 </t>
    3726 <t>
    3727   Take over definition of CONNECT method from <xref target="RFC2817"/>.
    3728   (<xref target="CONNECT"/>)
    37293701</t>
    37303702<t>
Note: See TracChangeset for help on using the changeset viewer.