Ignore:
Timestamp:
30/12/12 00:22:16 (9 years ago)
Author:
fielding@…
Message:

(editorial) clarify that header fields are refined by method and status code semantics; more rephrasing to identify subject of requirements; partly addresses #419

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r2065 r2067  
    779779   <list style="symbols">
    780780    <t>For a response to a GET or HEAD request, this is an indication that the
    781        effective request URI identifies a resource that is subject to content
     781       effective request URI refers to a resource that is subject to content
    782782       negotiation and the Content-Location field-value is a more specific
    783783       identifier for the selected representation.</t>
    … …  
    796796</t>
    797797<t>
    798    If Content-Location is included in a request message, then it &MAY;
    799    be interpreted by the origin server as an indication of where the
    800    user agent originally obtained the content of the enclosed
    801    representation (prior to any subsequent modification of the content
    802    by that user agent).  In other words, the user agent is providing
    803    the same representation metadata that it received with the original
    804    representation.  However, such interpretation &MUST-NOT; be used to
    805    alter the semantics of the method requested by the client.  For
    806    example, if a client makes a PUT request on a negotiated resource
    807    and the origin server accepts that PUT (without redirection), then the
    808    new set of values for that resource is expected to be consistent with
    809    the one representation supplied in that PUT; the Content-Location
    810    cannot be used as a form of reverse content selection that
    811    identifies only one of the negotiated representations to be updated.
    812    If the user agent had wanted the latter semantics, it would have applied
    813    the PUT directly to the Content-Location URI.
    814 </t>
    815 <t>
    816    A Content-Location field received in a request message is transitory
    817    information that &SHOULD-NOT; be saved with other representation
    818    metadata for use in later responses.  The Content-Location's value
    819    might be saved for use in other contexts, such as within source links
    820    or other metadata.
    821 </t>
    822 <t>
    823    A cache cannot assume that a representation with a Content-Location
    824    different from the URI used to retrieve it can be used to respond to
    825    later requests on that Content-Location URI.
     798   A user agent that sends Content-Location in a request message is stating
     799   that its value refers to where the user agent originally obtained the
     800   content of the enclosed representation (prior to any modifications made by
     801   that user agent).  In other words, the user agent is providing a back link
     802   to the source of the original representation.
     803</t>
     804<t>
     805   An origin server that receives a Content-Location field in a request
     806   message &MUST; treat the information as transitory request context rather
     807   than as metadata to be saved verbatim as part of the representation.
     808   An origin server &MAY; use that context to guide in processing the
     809   request or to save it for other uses, such as within source links or
     810   versioning metadata. However, an origin server &MUST-NOT; use such context
     811   information to alter the request semantics.
     812</t>
     813<t>
     814   For example, if a client makes a PUT request on a negotiated resource and
     815   the origin server accepts that PUT (without redirection), then the new set
     816   of values for that resource is expected to be consistent with the one
     817   representation supplied in that PUT; the Content-Location cannot be used as
     818   a form of reverse content selection identifier to update only one of the
     819   negotiated representations. If the user agent had wanted the latter
     820   semantics, it would have applied the PUT directly to the Content-Location
     821   URI.
    826822</t>
    827823</section>
    … …  
    30263022   <x:ref>target resource</x:ref> does not have a representation of
    30273023   its own that can be transferred by the server over HTTP.
    3028    The <x:ref>Location</x:ref> URI identifies a resource that is descriptive
    3029    of the target resource, such that the follow-on representation might be
    3030    useful to recipients without implying that it adequately represents the
    3031    target resource. Note that answers to the questions of what can be
    3032    represented, what representations are adequate, and what might be a useful
    3033    description are outside the scope of HTTP and thus entirely determined by
    3034    the URI owner(s).
     3024   The <x:ref>Location</x:ref> field value refers to a resource that is
     3025   descriptive of the target resource, such that the follow-on representation
     3026   might be useful to recipients without implying that it adequately
     3027   represents the target resource. Note that answers to the questions of what
     3028   can be represented, what representations are adequate, and what might be a
     3029   useful description are outside the scope of HTTP.
    30353030</t>
    30363031<t>
    … …  
    34553450<t>
    34563451   The response header fields allow the server to pass additional
    3457    information about the response which cannot be placed in the status-line.
    3458    These header fields give information about the server and about
    3459    further access to the <x:ref>target resource</x:ref>.
     3452   information about the response beyond what is placed in the status-line.
     3453   These header fields give information about the server, about
     3454   further access to the <x:ref>target resource</x:ref>, or about related
     3455   resources.
     3456</t>
     3457<t>
     3458   Although each response header field has a defined meaning, in general,
     3459   the precise semantics might be further refined by the semantics of the
     3460   request method and/or response status code.
    34603461</t>
    34613462
    … …  
    36753676  <x:anchor-alias value="Location"/>
    36763677<t>
    3677    The "Location" header field &MAY; be sent in responses to refer to
    3678    a specific resource in accordance with the semantics of the status
    3679    code.
     3678   The "Location" header field is used in some responses to refer to a
     3679   specific resource in relation to the response. The type of relationship is
     3680   defined by the combination of request method and status code semantics.
    36803681</t>
    36813682<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Location"/>
    36823683  <x:ref>Location</x:ref> = <x:ref>URI-reference</x:ref>
    36833684</artwork></figure>
    3684 <t>
    3685    For <x:ref>201 (Created)</x:ref> responses, the Location is the URI of the
    3686    new resource which was created by the request. For <x:ref>3xx (Redirection)</x:ref>
    3687    responses, the location &SHOULD; indicate the server's preferred URI for
    3688    automatic redirection to the resource.
    3689 </t>
    36903685<t>
    36913686   The field value consists of a single URI-reference. When it has the form
    … …  
    36933688   the final value is computed by resolving it against the effective request
    36943689   URI (<xref target="RFC3986" x:fmt="," x:sec="5"/>). If the original URI, as
    3695    navigated to by the user agent, did contain a fragment identifier, and the
    3696    final value does not, then the original URI's fragment identifier is added
    3697    to the final value.
     3690   navigated to by the user agent, contains a fragment identifier, and the
     3691   Location value does not, then the original URI's fragment identifier is
     3692   appended to the Location value.
     3693</t>
     3694<t>
     3695   For <x:ref>201 (Created)</x:ref> responses, the Location value refers to
     3696   the primary resource created by the request.
     3697   For <x:ref>3xx (Redirection)</x:ref> responses, the Location value refers
     3698   to the preferred target resource for automatically redirecting the request.
    36983699</t>
    36993700<figure>
    3700 <preamble>For example, the original URI "http://www.example.org/~tim", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc-->
     3701<preamble>For example, a GET request for the URI reference
     3702   "http://www.example.org/~tim" might result in a
     3703   <x:ref>303 (See Other)</x:ref> response containing the header field:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc-->
    37013704<artwork type="example">
    37023705  Location: /pub/WWW/People.html#tim
    37033706</artwork>
    3704 <postamble>would result in a final value of "http://www.example.org/pub/WWW/People.html#tim"</postamble>
     3707<postamble>which suggests that the user agent redirect to
     3708   "http://www.example.org/pub/WWW/People.html#tim"</postamble>
    37053709</figure>
    37063710<figure>
    3707 <preamble>An original URI "http://www.example.org/index.html#larry", combined with a field value given as:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc-->
     3711<preamble>Likewise, a GET request for the URI reference
     3712   "http://www.example.org/index.html#larry" might result in a
     3713   <x:ref>301 (Moved Permanently)</x:ref> response containing the header
     3714   field:</preamble><!--DO NOT DARE changing the vertical spacing below, it's necessary this way for xml2rfc-->
    37083715<artwork type="example">
    37093716  Location: http://www.example.net/index.html
    37103717</artwork>
    3711 <postamble>would result in a final value of "http://www.example.net/index.html#larry", preserving the original fragment identifier.</postamble>
     3718<postamble>which suggests that the user agent redirect to
     3719   "http://www.example.net/index.html#larry", preserving the original fragment
     3720   identifier.</postamble>
    37123721</figure>
     3722<t>
     3723   There are circumstances in which a fragment identifier in a Location
     3724   value would not be appropriate. For example, the Location header field in a
     3725   <x:ref>201 (Created)</x:ref> response is supposed to provide a URI that is
     3726   specific to the created resource.
     3727</t>
    37133728<x:note>
    37143729  <t>
    37153730    &Note; Some recipients attempt to recover from Location fields
    37163731    that are not valid URI references. This specification does not mandate or
    3717     define such processing, but does allow it.
     3732    define such processing, but does allow it for the sake of robustness.
    37183733  </t>
    37193734</x:note>
    3720 <t>
    3721    There are circumstances in which a fragment identifier in a Location URI
    3722    would not be appropriate. For instance, when it appears in a <x:ref>201
    3723    (Created)</x:ref> response, where the Location header field specifies the
    3724    URI for the entire created resource.
    3725 </t>
    37263735<x:note>
    37273736  <t>
    37283737    &Note; The <x:ref>Content-Location</x:ref> header field
    37293738    (&header-content-location;) differs from Location in that the
    3730     Content-Location identifies the most specific resource corresponding to the
     3739    Content-Location refers to the most specific resource corresponding to the
    37313740    enclosed representation. It is therefore possible for a response to contain
    3732     header fields for both Location and Content-Location.
     3741    both the Location and Content-Location header fields.
    37333742  </t>
    37343743</x:note>
    … …  
    39803989</t>
    39813990<t>
    3982    New method definitions need to indicate whether they are safe (<xref
     3991   A new method definition needs to indicate whether it is safe (<xref
    39833992   target="safe.methods"/>), idempotent (<xref target="idempotent.methods"/>),
    3984    cacheable (<xref target="cacheable.methods"/>), and what
     3993   cacheable (<xref target="cacheable.methods"/>), what
    39853994   semantics are to be associated with the payload body if any is present
    3986    in the request.  If a method is cacheable, the method definition ought
    3987    to describe how, and under what conditions, a cache can store a response
    3988    and use it to satisfy a subsequent request.
     3995   in the request, and what refinements the method makes to header field
     3996   or status code semantics.
     3997   If the new method is cacheable, its definition ought to describe how, and
     3998   under what conditions, a cache can store a response and use it to satisfy a
     3999   subsequent request.
     4000   If the new method can be made conditional (<xref target="Part4"/>), the
     4001   definition ought to describe how to respond when the condition is false.
     4002   Likewise, if the new method might have some use for partial response
     4003   semantics (<xref target="Part5"/>), it ought to document this too.
    39894004</t>
    39904005</section>
    … …  
    40784093   When it is necessary to express semantics for a response that are not
    40794094   defined by current status codes, a new status code can be registered.
    4080    HTTP status codes are generic; they are potentially applicable to
    4081    any resource, not just one particular media type, "type" of resource, or
    4082    application. As such, it is preferred that new status codes be
    4083    registered in a document that isn't specific to a single application.
     4095   Status codes are generic; they are potentially applicable to any resource,
     4096   not just one particular media type, kind of resource, or application of
     4097   HTTP. As such, it is preferred that new status codes be registered in a
     4098   document that isn't specific to a single application.
    40844099</t>
    40854100<t>
    40864101   New status codes are required to fall under one of the categories
    40874102   defined in <xref target="status.codes"/>. To allow existing parsers to
    4088    properly handle them, new status codes cannot disallow a payload,
     4103   process the response message, new status codes cannot disallow a payload,
    40894104   although they can mandate a zero-length payload body.
    40904105</t>
    … …  
    40934108   conditions that would cause a response containing that status code (e.g.,
    40944109   combinations of request header fields and/or method(s)) along with any
    4095    dependencies on response header fields (e.g., what fields are required
    4096    and what fields can modify the semantics). A response that can transfer a
    4097    payload ought to specify expected cache behavior (e.g., cacheability and
    4098    freshness criteria, as described in &caching;) and whether the payload has
    4099    any implied association with an identified resource
    4100    (<xref target="identifying.payload"/>).
     4110   dependencies on response header fields (e.g., what fields are required,
     4111   what fields can modify the semantics, and what header field semantics are
     4112   further refined when used with the new status code).
     4113</t>
     4114<t>
     4115   A response that can transfer a payload ought to specify expected cache
     4116   behavior (e.g., cacheability and freshness criteria, as described in
     4117   &caching;) and whether the payload has any implied association with an
     4118   identified resource (<xref target="identifying.payload"/>).
    41014119</t>
    41024120</section>
    … …  
    43674385      (delimited by commas; see &header-fields;).</t>
    43684386      <t>If it does not use the list syntax, document how to treat messages
    4369       where the header field occurs multiple times (a sensible default would
    4370       be to ignore the header field, but this might not always be the right
     4387      where the field occurs multiple times (a sensible default would
     4388      be to ignore the field, but this might not always be the right
    43714389      choice).</t>
    43724390      <t>Note that intermediaries and software libraries might combine
    4373       multiple header field instances into a single one, despite the header
    4374       field not allowing this. A robust format enables recipients to discover
    4375       these situations (good example: "Content-Type", as the comma can only
    4376       appear inside quoted strings; bad example: "Location", as a comma can
    4377       occur inside a URI).</t>
     4391      multiple header field instances into a single one, despite the
     4392      field's definition not allowing the list syntax. A robust format enables
     4393      recipients to discover these situations (good example: "Content-Type",
     4394      as the comma can only appear inside quoted strings;
     4395      bad example: "Location", as a comma can occur inside a URI).</t>
    43784396    </x:lt>
    43794397    <x:lt><t>Under what conditions the header field can be used; e.g., only in
    4380     responses or requests, in all messages, only on responses to a particular
    4381     request method.</t></x:lt>
     4398      responses or requests, in all messages, only on responses to a
     4399      particular request method, etc.</t></x:lt>
     4400    <x:lt><t>Whether the field semantics are further refined by the context,
     4401      such as by existing request methods or status codes.</t></x:lt>
    43824402    <x:lt><t>Whether it is appropriate to list the field-name in the
    4383     <x:ref>Connection</x:ref> header field (i.e., if the header field is to
    4384     be hop-by-hop; see &header-connection;).</t></x:lt>
    4385     <x:lt><t>Under what conditions intermediaries are allowed to modify the header
    4386     field's value, insert or delete it.</t></x:lt>
     4403      <x:ref>Connection</x:ref> header field (i.e., if the header field is to
     4404      be hop-by-hop; see &header-connection;).</t></x:lt>
     4405    <x:lt><t>Under what conditions intermediaries are allowed to insert,
     4406      delete, or modify the field's value.</t></x:lt>
    43874407    <x:lt><t>How the header field might interact with caching (see
    4388     <xref target="Part6"/>).</t></x:lt>
     4408      <xref target="Part6"/>).</t></x:lt>
    43894409    <x:lt><t>Whether the header field is useful or allowable in trailers (see
    4390     &chunked-encoding;).</t></x:lt>
     4410      &chunked-encoding;).</t></x:lt>
    43914411    <x:lt><t>Whether the header field ought to be preserved across redirects.</t></x:lt>
    43924412  </list>
    … …  
    46194639   method of determining the sensitivity of any particular piece of
    46204640   information within the context of any given request. Therefore,
    4621    applications &SHOULD; supply as much control over this information as
     4641   applications ought to supply as much control over this information as
    46224642   possible to the provider of that information. Four header fields are
    46234643   worth special mention in this context: <x:ref>Server</x:ref>,
    … …  
    46314651</t>
    46324652<t>
    4633    Proxies which serve as a portal through a network firewall &SHOULD;
     4653   Proxies that serve as a portal through a network firewall &SHOULD;
    46344654   take special precautions regarding the transfer of header information
    4635    that identifies the hosts behind the firewall. In particular, they
     4655   that might identify hosts behind the firewall. In particular, they
    46364656   &SHOULD; remove, or replace with sanitized versions, any <x:ref>Via</x:ref>
    46374657   fields generated behind the firewall.
Note: See TracChangeset for help on using the changeset viewer.