Ignore:
Timestamp:
27/08/12 06:21:21 (8 years ago)
Author:
fielding@…
Message:

Move method registry to IANA considerations.
Rewrite definitions of safe and idempotent; add cacheable.

File:
1 edited

Legend:

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

    r1839 r1840  
    327327   <ttcol>Sec.</ttcol>
    328328   <c>GET</c>
    329    <c>Retrieve a current representation of the target resource.</c>
     329   <c>Transfer a current representation of the target resource.</c>
    330330   <c><xref target="GET" format="counter"/></c>
    331331   <c>HEAD</c>
     
    354354<t>
    355355   The methods GET and HEAD &MUST; be supported by all general-purpose
    356    servers. All other methods are &OPTIONAL;. If one of the above methods is
    357    implemented by a server, the server &MUST; implement that method according
    358    to the semantics defined for it in <xref target="method.definitions"/>.
    359 </t>
    360 <t>
    361    Additional methods &MAY; be used in HTTP.  New methods &SHOULD; be
    362    registered within the IANA registry, as defined in
     356   servers. All other methods are &OPTIONAL;.
     357   When implemented, a server &MUST; implement the above methods according
     358   to the semantics defined for them in <xref target="method.definitions"/>.
     359</t>
     360<t>
     361   Additional methods &MAY; be used in HTTP; many have already been
     362   standardized outside the scope of this specification and registered
     363   within the HTTP Method Registry maintained by IANA, as defined in
    363364   <xref target="method.registry"/>.
    364365</t>
     
    377378
    378379<section title="Safe Methods" anchor="safe.methods">
    379 <iref item="Safe Methods" primary="true"/>
     380<iref item="safe" primary="true"/>
    380381<t>
    381382   Request methods are considered "<x:dfn anchor="safe">safe</x:dfn>" if
    382    their defined semantics are essentially read-only; i.e., the user does
     383   their defined semantics are essentially read-only; i.e., the client does
    383384   not request, and does not expect, any state change on the origin server
    384385   as a result of applying a safe method to a target resource.  Likewise,
     
    389390   This definition of safe methods does not prevent an implementation from
    390391   including behavior that is potentially harmful, not entirely read-only,
    391    or which causes side-effects while invoking a safe method.  In fact,
    392    some dynamic resources might consider that a feature.  What is
    393    important, however, is that the user did not request that additional
     392   or which causes side-effects while invoking a safe method.  What is
     393   important, however, is that the client did not request that additional
    394394   behavior and cannot be held accountable for it.  For example,
    395395   most servers append request information to access log files at the
    396396   completion of every response, regardless of the method, and that is
    397397   considered safe even though the log storage might become full and crash
    398    the server.
     398   the server.  Likewise, a safe request initiated by selecting an
     399   advertisement on the Web will often have the side-effect of charging an
     400   advertising account.
    399401</t>
    400402<t>
    401403   The GET, HEAD, OPTIONS, and TRACE request methods are defined to be safe.
     404</t>
     405<t>
     406   The purpose of distinguishing between safe and unsafe methods is to
     407   allow automated retrieval processes (spiders) and cache performance
     408   optimization (pre-fetching) to work without fear of causing harm.
     409   In addition, it allows a user agent to apply appropriate constraints
     410   on the automated use of unsafe methods when processing potentially
     411   untrusted content.
    402412</t>
    403413<t>
     
    405415   presenting potential actions to a user, such that the user can be made
    406416   aware of an unsafe action before it is requested.
    407    A user agent &SHOULD-NOT; make requests using unsafe methods as an
    408    automated result of the user selecting a safe action, unless the
    409    instruction for making the unsafe request came from the same origin server
    410    as the request target.
    411417</t>
    412418<t>
     
    415421   owner's responsibility to ensure that the action is consistent with the
    416422   request method semantics.
    417    For example, it is common for HTML form-based content editing software
     423   For example, it is common for Web-based content editing software
    418424   to use actions within query parameters, such as "page?do=delete".
    419425   If the purpose of such a resource is to perform an unsafe action, then
     
    421427   using a safe request method.  Failure to do so will result in
    422428   unfortunate side-effects when automated processes perform a GET on
    423    every URI reference, which often occurs for the sake of link maintenance,
    424    pre-fetching, or building a search index.
     429   every URI reference for the sake of link maintenance, pre-fetching,
     430   building a search index, etc.
    425431</t>
    426432</section>
    427433
    428434<section title="Idempotent Methods" anchor="idempotent.methods">
    429 <iref item="Idempotent Methods" primary="true"/>
    430 <t>
    431    Request methods can also have the property of "idempotence" in that,
    432    aside from error or expiration issues, the intended effect of multiple
    433    identical requests is the same as for a single request.
     435<iref item="idempotent" primary="true"/>
     436<t>
     437   Request methods are considered
     438   "<x:dfn anchor="idempotent">idempotent</x:dfn>" if the intended effect
     439   of multiple identical requests is the same as for a single request.
    434440   PUT, DELETE, and all safe request methods are idempotent.
    435    It is important to note that idempotence refers only to changes
    436    requested by the client: a server is free to change its state due
    437    to multiple requests for the purpose of tracking those requests,
    438    versioning of results, etc.
    439 </t>
    440 </section>
    441 </section>
    442 
    443 <section title="Method Registry" anchor="method.registry">
    444 <t>
    445   The HTTP Method Registry defines the name space for the method token in the
    446   Request line of an HTTP request.
    447 </t>
    448 <t>
    449   Registrations &MUST; include the following fields:
    450   <list style="symbols">
    451     <t>Method Name (see <xref target="methods"/>)</t>
    452     <t>Safe ("yes" or "no", see <xref target="safe.methods"/>)</t>
    453     <t>Idempotent ("yes" or "no", see <xref target="safe.methods"/>)</t>
    454     <t>Pointer to specification text</t>
    455   </list>
    456 </t>
    457 <t>
    458   Values to be added to this name space require IETF Review
    459   (see <xref target="RFC5226" x:fmt="," x:sec="4.1"/>).
    460 </t>
    461 <t>
    462   The registry itself is maintained at <eref target="http://www.iana.org/assignments/http-methods"/>.
    463 </t>
    464 
    465 <section title="Considerations for New Methods" anchor="considerations.for.new.methods">
    466 <t>
    467    When it is necessary to express new semantics for a HTTP request that
    468    aren't specific to a single application or media type, and currently defined
    469    methods are inadequate, it might be appropriate to register a new method.
    470 </t>
    471 <t>
    472    HTTP methods are generic; that is, they are potentially applicable to any
    473    resource, not just one particular media type, "type" of resource, or
    474    application. As such, it is preferred that new HTTP methods be registered
    475    in a document that isn't specific to a single application, so that this is
    476    clear.
    477 </t>
    478 <t>
    479    Due to the parsing rules defined in &message-body;, definitions of HTTP
    480    methods cannot prohibit the presence of a message body on either the request
    481    or the response message (with responses to HEAD requests being the single
    482    exception). Definitions of new methods cannot change this rule, but they can
    483    specify that only zero-length bodies (as opposed to absent bodies) are allowed.
    484 </t>
    485 <t>
    486    New method definitions need to indicate whether they are safe (<xref
    487    target="safe.methods"/>), what semantics (if any) the request body has,
    488    and whether they are idempotent (<xref target="idempotent.methods"/>).
    489    They also need to state whether they can be cached (&caching;); in
    490    particular under what conditions a cache can store the response, and under
    491    what conditions such a stored response can be used to satisfy a subsequent
    492    request.
     441</t>
     442<t>
     443   Like the definition of safe, the idempotent property only applies to
     444   what has been requested by the user; a server is free to log each request
     445   separately, retain a revision control history, or implement other
     446   non-idempotent side-effects for each idempotent request.
     447</t>
     448<t>
     449   Idempotent methods are distinguished because the request can be repeated
     450   automatically if a communication failure occurs before the client is
     451   able to read the server's response.  For example, if a client sends a PUT
     452   request and the underlying connection is closed before any response is
     453   received, then it can establish a new connection and retry the request
     454   because it knows that repeating the request will have the same effect
     455   even if the original request succeeded.  Note, however, that repeated
     456   failures would indicate a problem within the server.
     457</t>
     458</section>
     459
     460<section title="Cacheable Methods" anchor="cacheable.methods">
     461<iref item="cacheable" primary="true"/>
     462<t>
     463   Request methods are considered
     464   "<x:dfn anchor="cacheable">cacheable</x:dfn>" if it is possible and useful
     465   to answer a current client request with a stored response from a prior
     466   request.  GET and HEAD are defined to be cacheable.  In general, safe
     467   methods that do not depend on a current or authoritative response are
     468   also cacheable, though the overwhelming majority of caches only support
     469   GET and HEAD. HTTP requirements for cache behavior and cacheable responses
     470   are defined in &caching;.
    493471</t>
    494472</section>
     
    40434021<section title="IANA Considerations" anchor="IANA.considerations">
    40444022
    4045 <section title="Method Registry" anchor="method.registration">
    4046 <t>
    4047   The registration procedure for HTTP request methods is defined by
    4048   <xref target="method.registry"/> of this document.
    4049 </t>
     4023<section title="Method Registry" anchor="method.registry">
     4024<t>
     4025  The HTTP Method Registry defines the name space for the method token in the
     4026  Request line of an HTTP request.
     4027</t>
     4028<t>
     4029  Registrations &MUST; include the following fields:
     4030  <list style="symbols">
     4031    <t>Method Name (see <xref target="methods"/>)</t>
     4032    <t>Safe ("yes" or "no", see <xref target="safe.methods"/>)</t>
     4033    <t>Idempotent ("yes" or "no", see <xref target="safe.methods"/>)</t>
     4034    <t>Pointer to specification text</t>
     4035  </list>
     4036</t>
     4037<t>
     4038  Values to be added to this name space require IETF Review
     4039  (see <xref target="RFC5226" x:fmt="," x:sec="4.1"/>).
     4040</t>
     4041<t>
     4042  The registry itself is maintained at <eref target="http://www.iana.org/assignments/http-methods"/>.
     4043</t>
     4044
     4045<section title="Considerations for New Methods" anchor="considerations.for.new.methods">
     4046<t>
     4047   Standardized HTTP methods are generic; that is, they are potentially
     4048   applicable to any resource, not just one particular media type, kind of
     4049   resource, or application. As such, it is preferred that new HTTP methods
     4050   be registered in a document that isn't specific to a single application or
     4051   data format, since orthogonal technologies deserve orthogonal specification.
     4052</t>
     4053<t>
     4054   Since HTTP message parsing (&message-body;) is independent of method
     4055   semantics (aside from responses to HEAD), definitions of new HTTP methods
     4056   cannot change the parsing algorithm or prohibit the presence of a message
     4057   body on either the request or the response message.
     4058   Definitions of new methods can specify that only zero-length bodies are
     4059   allowed, which would imply that each such messages would be required to
     4060   contain a Content-Length header field with a value of "0".
     4061</t>
     4062<t>
     4063   New method definitions need to indicate whether they are safe (<xref
     4064   target="safe.methods"/>), idempotent (<xref target="idempotent.methods"/>),
     4065   or cacheable (<xref target="cacheable.methods"/>), and what
     4066   semantics are to be associated with the request body if any is present
     4067   in the request.  If a method is cacheable, the method definition ought
     4068   to describe how, and under what conditions, a cache can store a response
     4069   and use it to satisfy a subsequent request.
     4070</t>
     4071</section>
     4072
     4073<section title="Registrations" anchor="method.registration">
    40504074<t>
    40514075   The HTTP Method Registry shall be created at <eref target="http://www.iana.org/assignments/http-methods"/>
     
    41104134<!--(END)-->
    41114135<?ENDINC p2-semantics.iana-methods ?>
     4136</section>
    41124137</section>
    41134138
Note: See TracChangeset for help on using the changeset viewer.