Ignore:
Timestamp:
25/08/12 09:08:32 (8 years ago)
Author:
fielding@…
Message:

Begin plowing through p2 to properly explain what HTTP semantics are and why.
Rewrite introductory description of methods.
Rewrite definition of "safe" to be more operable and weaken the original
same-origin restrictions to be more consistent with modern UAs.

File:
1 edited

Legend:

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

    r1831 r1839  
    1818  <!ENTITY Note "<x:h xmlns:x='http://purl.org/net/xml2rfc/ext'>Note:</x:h>">
    1919  <!ENTITY architecture               "<xref target='Part1' x:rel='#architecture' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     20  <!ENTITY conformance                "<xref target='Part1' x:rel='#conformance' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2021  <!ENTITY notation                   "<xref target='Part1' x:rel='#notation' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    2122  <!ENTITY acks                       "<xref target='Part1' x:rel='#acks' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     
    216217   responds to that request with one or more response messages.
    217218   This document defines HTTP/1.1 request and response semantics in terms of
    218    the architecture, syntax notation, and conformance criteria defined in
    219    <xref target="Part1"/>.
     219   the architecture defined in <xref target="Part1"/>.
    220220</t>
    221221<t>
    222222   HTTP provides a uniform interface for interacting with resources regardless
    223223   of their type, nature, or implementation.  HTTP semantics includes the
    224    intentions defined by each request method, extensions to those semantics
    225    that might be described in request header fields, the meaning of status
    226    codes to indicate a machine-readable response, and additional control data
     224   intentions defined by each request method (<xref target="methods"/>),
     225   extensions to those semantics that might be described in request header
     226   fields (<xref target="request.fields"/>),
     227   the meaning of status codes to indicate a machine-readable response
     228   (<xref target="status.codes"/>), and other control data
    227229   and resource metadata that might be given in response header fields.
    228230</t>
     
    235237   "<x:dfn>content negotiation</x:dfn>".
    236238</t>
    237 <x:note><t>
    238    &Note; This document is currently disorganized in order to minimize changes
    239    between drafts and enable reviewers to see the smaller errata changes.
    240    A future draft will reorganize the sections to better reflect the content.
    241    In particular, the sections will be ordered according to the typical
    242    processing of an HTTP request message (after message parsing): resource
    243    mapping, methods, request modifying header fields, response status,
    244    status modifying header fields, and resource metadata.  The current mess
    245    reflects how widely dispersed these topics and associated requirements
    246    had become in <xref target="RFC2616"/>.
    247 </t></x:note>
    248 <section title="Conformance and Error Handling" anchor="intro.conformance.and.error.handling">
     239<section title="Conformance and Error Handling" anchor="conformance">
    249240<t>
    250241   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
     
    253244</t>
    254245<t>
    255    This specification targets conformance criteria according to the role of
    256    a participant in HTTP communication.  Hence, HTTP requirements are placed
    257    on senders, recipients, clients, servers, user agents, intermediaries,
    258    origin servers, proxies, gateways, or caches, depending on what behavior
    259    is being constrained by the requirement. See &architecture; for definitions
    260    of these terms.
    261 </t>
    262 <t>
    263    The verb "generate" is used instead of "send" where a requirement
    264    differentiates between creating a protocol element and merely forwarding a
    265    received element downstream.
    266 </t>
    267 <t>
    268    An implementation is considered conformant if it complies with all of the
    269    requirements associated with the roles it partakes in HTTP. Note that
    270    SHOULD-level requirements are relevant here, unless one of the documented
    271    exceptions is applicable.
    272 </t>
    273 <t>
    274    This document also uses ABNF to define valid protocol elements
    275    (<xref target="notation"/>).
    276    In addition to the prose requirements placed upon them, senders &MUST-NOT;
    277    generate protocol elements that do not match the grammar defined by the
    278    ABNF rules for those protocol elements that are applicable to the sender's
    279    role. If a received protocol element is processed, the recipient &MUST; be
    280    able to parse any value that would match the ABNF rules for that protocol
    281    element, excluding only those rules not applicable to the recipient's role.
    282 </t>
    283 <t>
    284    Unless noted otherwise, a recipient &MAY; attempt to recover a usable
    285    protocol element from an invalid construct.  HTTP does not define
    286    specific error handling mechanisms except when they have a direct impact
    287    on security, since different applications of the protocol require
    288    different error handling strategies.  For example, a Web browser might
    289    wish to transparently recover from a response where the
    290    <x:ref>Location</x:ref> header field doesn't parse according to the ABNF,
    291    whereas a systems control client might consider any form of error recovery
    292    to be dangerous.
     246   Conformance criteria and considerations regarding error handling
     247   are defined in &conformance;.
    293248</t>
    294249</section>
     
    305260</section>
    306261
    307 <section title="Methods" anchor="methods">
     262<section title="Resource" anchor="resource">
     263  <x:anchor-alias value="target resource"/>
     264<t>
     265   The target of each HTTP request is called a resource.
     266   HTTP does not limit the nature of a resource; it merely
     267   defines an interface that might be used to interact with resources.
     268   Each resource is identified by a Uniform Resource Identifier (URI), as
     269   described in &uri;.
     270</t>
     271<t>
     272   When a client constructs an HTTP/1.1 request message, it sends the
     273   "target URI" in one of various forms, as defined in
     274   (&request-target;). When a request is received, the server reconstructs
     275   an "effective request URI" for the target resource
     276   (&effective-request-uri;).
     277</t>
     278<t>
     279   One design goal of HTTP is to separate resource identification from
     280   request semantics, which is made possible by vesting the request
     281   semantics in the request method (<xref target="methods"/>) and a few
     282   request-modifying header fields (<xref target="request.fields"/>).
     283   Resource owners &SHOULD-NOT; include request semantics within a URI,
     284   such as by specifying an action to invoke within the path or query
     285   components of the effective request URI, unless those semantics are
     286   disabled when they are inconsistent with the request method.
     287</t>
     288</section>
     289
     290<section title="Request Methods" anchor="methods">
    308291  <x:anchor-alias value="method"/>
    309292<t>
    310    The method token indicates the request method to be performed on the target
    311    resource (&effective-request-uri;). The method is case-sensitive.
     293   The request method token is the primary source of request semantics;
     294   it indicates the purpose for which the client has made this request
     295   and what is expected by the client as a successful result.  The request
     296   semantics &MAY; be further specialized by the semantics of some header
     297   fields when present in a request (<xref target="request.fields"/>) if
     298   those additional semantics do not conflict with the method.
    312299</t>
    313300<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="method"/>
    314   <x:ref>method</x:ref>         = <x:ref>token</x:ref>
     301  <x:ref>method</x:ref> = <x:ref>token</x:ref>
    315302</artwork></figure>
    316303<t>
    317    The list of methods allowed by a resource can be specified in an
    318    <x:ref>Allow</x:ref> header field (<xref target="header.allow"/>). The
    319    status code of the response always notifies the client whether a method is
    320    currently allowed on a resource, since the set of allowed methods can change
    321    dynamically. An origin server &SHOULD; respond with the status code
    322    <x:ref>405 (Method Not Allowed)</x:ref> if the method is known by the origin
    323    server but not allowed for the resource, and <x:ref>501 (Not
    324    Implemented)</x:ref> if the method is unrecognized or not implemented by the
    325    origin server. The methods GET and HEAD &MUST; be supported by all
    326    general-purpose servers. All other methods are &OPTIONAL;; however, if the
    327    above methods are implemented, they &MUST; be implemented with the same
    328    semantics as those specified in <xref target="method.definitions"/>.
    329 </t>
    330 
    331 <section title="Safe and Idempotent Methods" anchor="safe.and.idempotent">
     304   HTTP was originally designed to be usable as an interface to distributed
     305   object systems.  The request method was envisioned as applying
     306   semantics to a target resource in much the same way as invoking a defined
     307   method on an identified object would apply semantics. The method token
     308   is case-sensitive because it might be used as a gateway to object-based
     309   systems with case-sensitive method names.
     310</t>
     311<t>
     312   Unlike distributed objects, the standardized request methods in HTTP are
     313   not resource-specific, since uniform interfaces provide for better
     314   visibility and reuse in network-based systems <xref target="REST"/>.
     315   Once defined, a standardized method &MUST; have the same semantics when
     316   applied to any resource, though each resource determines for itself
     317   whether those semantics are implemented or allowed.
     318</t>
     319<t>
     320   This specification defines a number of standardized methods that are
     321   commonly used in HTTP, as outlined by the following table. By convention,
     322   standardized methods are defined in all-uppercase ASCII letters.
     323</t>
     324<texttable align="left" suppress-title="true" anchor="method.overview">
     325   <ttcol>Method</ttcol>
     326   <ttcol>Description</ttcol>
     327   <ttcol>Sec.</ttcol>
     328   <c>GET</c>
     329   <c>Retrieve a current representation of the target resource.</c>
     330   <c><xref target="GET" format="counter"/></c>
     331   <c>HEAD</c>
     332   <c>Same as GET, but do not include a message body in the response.</c>
     333   <c><xref target="HEAD" format="counter"/></c>
     334   <c>POST</c>
     335   <c>Perform resource-specific processing on the request payload.</c>
     336   <c><xref target="POST" format="counter"/></c>
     337   <c>PUT</c>
     338   <c>Replace all current representations of the target resource with
     339      the request payload.</c>
     340   <c><xref target="PUT" format="counter"/></c>
     341   <c>DELETE</c>
     342   <c>Remove all current representations of the target resource.</c>
     343   <c><xref target="DELETE" format="counter"/></c>
     344   <c>CONNECT</c>
     345   <c>Establish a tunnel to the server identified by the target resource.</c>
     346   <c><xref target="CONNECT" format="counter"/></c>
     347   <c>OPTIONS</c>
     348   <c>Describe the communication options for the target resource.</c>
     349   <c><xref target="OPTIONS" format="counter"/></c>
     350   <c>TRACE</c>
     351   <c>Perform a message loop-back test along the path to the target resource.</c>
     352   <c><xref target="TRACE" format="counter"/></c>
     353</texttable>
     354<t>
     355   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
     363   <xref target="method.registry"/>.
     364</t>
     365<t>
     366   The set of methods allowed by a target resource can be listed in an
     367   <x:ref>Allow</x:ref> header field (<xref target="header.allow"/>).
     368   However, the set of allowed methods can change dynamically.
     369   When a request message is received that is unrecognized or not implemented
     370   by an origin server, the origin server &SHOULD; respond with the
     371   <x:ref>501 (Not Implemented)</x:ref> status code.
     372   When a request message is received that is known by an origin server but
     373   not allowed for the target resource, the origin server &SHOULD; respond
     374   with the <x:ref>405 (Method Not Allowed)</x:ref> status code.
     375</t>
     376<section title="Common Method Properties" anchor="method.properties">
    332377
    333378<section title="Safe Methods" anchor="safe.methods">
    334379<iref item="Safe Methods" primary="true"/>
    335380<t>
    336    Implementers need to be aware that the software represents the user in
    337    their interactions over the Internet, and need to allow
    338    the user to be aware of any actions they take which might have an
    339    unexpected significance to themselves or others.
    340 </t>
    341 <t>
    342    In particular, the convention has been established that the GET, HEAD,
    343    OPTIONS, and TRACE request methods &SHOULD-NOT; have the significance
    344    of taking an action other than retrieval. These request methods ought
    345    to be considered "<x:dfn anchor="safe">safe</x:dfn>".
    346    This allows user agents to represent other methods, such as POST, PUT
    347    and DELETE, in a special way, so that the user is made aware of the
    348    fact that a possibly unsafe action is being requested.
    349 </t>
    350 <t>
    351    Naturally, it is not possible to ensure that the server does not
    352    generate side-effects as a result of performing a GET request; in
    353    fact, some dynamic resources consider that a feature. The important
    354    distinction here is that the user did not request the side-effects,
    355    so therefore cannot be held accountable for them.
     381   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   not request, and does not expect, any state change on the origin server
     384   as a result of applying a safe method to a target resource.  Likewise,
     385   reasonable use of a safe method is not expected to cause any harm,
     386   loss of property, or unusual burden on the origin server.
     387</t>
     388<t>
     389   This definition of safe methods does not prevent an implementation from
     390   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
     394   behavior and cannot be held accountable for it.  For example,
     395   most servers append request information to access log files at the
     396   completion of every response, regardless of the method, and that is
     397   considered safe even though the log storage might become full and crash
     398   the server.
     399</t>
     400<t>
     401   The GET, HEAD, OPTIONS, and TRACE request methods are defined to be safe.
     402</t>
     403<t>
     404   A user agent &SHOULD; distinguish between safe and unsafe methods when
     405   presenting potential actions to a user, such that the user can be made
     406   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.
     411</t>
     412<t>
     413   When a resource is constructed such that parameters within the effective
     414   request URI have the effect of selecting an action, it is the resource
     415   owner's responsibility to ensure that the action is consistent with the
     416   request method semantics.
     417   For example, it is common for HTML form-based content editing software
     418   to use actions within query parameters, such as "page?do=delete".
     419   If the purpose of such a resource is to perform an unsafe action, then
     420   the resource &MUST; disable or disallow that action when it is accessed
     421   using a safe request method.  Failure to do so will result in
     422   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.
    356425</t>
    357426</section>
     
    914983   of their syntax.
    915984</t>
     985
     986<section title="Request-modifier Header Fields" anchor="request.fields">
     987</section>
     988
     989<section title="Status-modifier Header Fields" anchor="response.fields">
     990</section>
     991
     992<section title="Resource Metadata Fields" anchor="resource.fields">
     993</section>
     994
     995<section title="Payload Metadata Fields" anchor="payload.fields">
     996</section>
    916997
    917998<section title="Considerations for Creating Header Fields" anchor="considerations.for.creating.header.fields">
     
    10611142</section>
    10621143
    1063 <section title="Status Codes" anchor="status.codes">
     1144<section title="Response Status Codes" anchor="status.codes">
    10641145<t>
    10651146   The status-code element is a 3-digit integer result code of the attempt to
     
    49195000<references title="Informative References">
    49205001
     5002<reference anchor="REST" target="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">
     5003  <front>
     5004    <title>Architectural Styles and the Design of Network-based Software Architectures</title>
     5005    <author initials="R.T." surname="Fielding" fullname="Roy T. Fielding">
     5006      <organization>Doctoral Dissertation, University of California, Irvine</organization>
     5007    </author>
     5008    <date month="Sep" year="2000"/>
     5009  </front>
     5010</reference>
     5011
    49215012<reference anchor="RFC1123">
    49225013  <front>
     
    56685759<x:ref>Server</x:ref> = product *( RWS ( product / comment ) )
    56695760
    5670 <x:ref>URI-reference</x:ref> = &lt;URI-reference, defined in [Part1], Section 2.8&gt;
     5761<x:ref>URI-reference</x:ref> = &lt;URI-reference, defined in [Part1], Section 2.7&gt;
    56715762<x:ref>User-Agent</x:ref> = product *( RWS ( product / comment ) )
    56725763
    5673 <x:ref>absolute-URI</x:ref> = &lt;absolute-URI, defined in [Part1], Section 2.8&gt;
     5764<x:ref>absolute-URI</x:ref> = &lt;absolute-URI, defined in [Part1], Section 2.7&gt;
    56745765<x:ref>accept-ext</x:ref> = OWS ";" OWS token [ "=" word ]
    56755766<x:ref>accept-params</x:ref> = weight *accept-ext
     
    57355826
    57365827<x:ref>parameter</x:ref> = attribute "=" value
    5737 <x:ref>partial-URI</x:ref> = &lt;partial-URI, defined in [Part1], Section 2.8&gt;
     5828<x:ref>partial-URI</x:ref> = &lt;partial-URI, defined in [Part1], Section 2.7&gt;
    57385829<x:ref>product</x:ref> = token [ "/" product-version ]
    57395830<x:ref>product-version</x:ref> = token
Note: See TracChangeset for help on using the changeset viewer.