Ignore:
Timestamp:
Mar 31, 2011, 5:51:27 AM (9 years ago)
Author:
fielding@…
Message:

Rearrange sections to match the story (no content change).
Add reference to Part 6. Define "validator". Adjust titles.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p4-conditional.xml

    r1251 r1253  
    221221   specify preconditions to be checked before performing the action
    222222   given by the request method.  Conditional GET requests are the most
    223    efficient mechanism for HTTP cache updates.  Conditionals can be
     223   efficient mechanism for HTTP cache updates &caching;.  Conditionals can be
    224224   applied to state-changing methods, such as PUT and DELETE, to prevent
    225225   the "lost update" problem: one client accidentally overwriting
     
    304304</section>
    305305
    306 <section title="Resource State Metadata" anchor="resource.metadata">
     306<section title="Resource State Metadata (Validators)" anchor="resource.metadata">
     307   <iref primary="true" item="metadata"/>
     308   <iref primary="true" item="validator"/>
    307309<t>
    308310   This specification defines two forms of metadata that are commonly used
     
    311313   has been defined by various extensions of HTTP, such as WebDAV
    312314   <xref target="RFC4918"/>, that are beyond the scope of this specification.
    313 </t>
     315   Such metadata is referred to as a "<x:dfn>validator</x:dfn>" when it is
     316   used within a precondition.
     317</t>
     318
     319<section title="Last-Modified" anchor="header.last-modified">
     320  <iref primary="true" item="Last-Modified header field" x:for-anchor=""/>
     321  <iref primary="true" item="Header Fields" subitem="Last-Modified" x:for-anchor=""/>
     322  <x:anchor-alias value="Last-Modified"/>
     323<t>
     324   The "Last-Modified" header field indicates the date and time at
     325   which the origin server believes the representation was last modified.
     326</t>
     327<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Last-Modified"/>
     328  <x:ref>Last-Modified</x:ref> = <x:ref>HTTP-date</x:ref>
     329</artwork></figure>
     330<t>
     331   An example of its use is
     332</t>
     333<figure><artwork type="example">
     334  Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
     335</artwork></figure>
     336<t>
     337   A representation is typically the sum of many parts behind the
     338   resource interface.  The last-modified time would usually be
     339   the most recent time that any of those parts were changed.
     340   How that value is determined for any given resource is an
     341   implementation detail beyond the scope of this specification.
     342   What matters to HTTP is how recipients of the Last-Modified
     343   header field can use its value to make conditional requests
     344   and test the validity of locally cached responses.
     345</t>
     346<t>
     347   An origin server &MUST-NOT; send a Last-Modified date which is later
     348   than the server's time of message origination. In such cases, where
     349   the resource's last modification would indicate some time in the
     350   future, the server &MUST; replace that date with the message
     351   origination date.
     352</t>
     353<t>
     354   An origin server &SHOULD; obtain the Last-Modified value of the representation
     355   as close as possible to the time that it generates the Date value of
     356   its response. This allows a recipient to make an accurate assessment
     357   of the representation's modification time, especially if the representation changes
     358   near the time that the response is generated.
     359</t>
     360<t>
     361   HTTP/1.1 servers &SHOULD; send Last-Modified whenever feasible.
     362</t>
     363<t>
     364   The Last-Modified header field value is often used as a cache
     365   validator. In simple terms, a cache entry is considered to be valid
     366   if the representation has not been modified since the Last-Modified value.
     367</t>
     368</section>
    314369
    315370<section title="Entity Tags" anchor="entity.tags">
     
    353408</t>
    354409
     410<section title="ETag" anchor="header.etag">
     411  <iref primary="true" item="ETag header field" x:for-anchor=""/>
     412  <iref primary="true" item="Header Fields" subitem="ETag" x:for-anchor=""/>
     413  <x:anchor-alias value="ETag"/>
     414<t>
     415   The "ETag" header field provides the current value of the
     416   entity-tag (see <xref target="entity.tags"/>) for one representation of
     417   the target resource.  An entity-tag
     418   is intended for use as a resource-local identifier for differentiating
     419   between representations of the same resource that vary over time or via
     420   content negotiation (see <xref target="weak.and.strong.validators"/>).
     421</t>
     422<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ETag"/>
     423  <x:ref>ETag</x:ref> = <x:ref>entity-tag</x:ref>
     424</artwork></figure>
     425<figure><preamble>
     426  Examples:
     427</preamble>
     428<artwork type="example">
     429  ETag: "xyzzy"
     430  ETag: W/"xyzzy"
     431  ETag: ""
     432</artwork></figure>
     433<t>
     434   An entity-tag provides an "opaque" cache validator that allows for
     435   more reliable validation than modification dates in situations where
     436   it is inconvenient to store modification dates,
     437   where the one-second resolution of HTTP date values is not
     438   sufficient, or where the origin server wishes to avoid certain
     439   paradoxes that might arise from the use of modification dates.
     440</t>
     441<t>
     442   The principle behind entity-tags is that only the service author
     443   knows the semantics of a resource well enough to select an
     444   appropriate cache validation mechanism, and the specification of any
     445   validator comparison function more complex than byte-equality would
     446   open up a can of worms. Thus, comparisons of any other header fields
     447   (except Last-Modified, for compatibility with HTTP/1.0) are never
     448   used for purposes of validating a cache entry.
     449</t>
     450</section>
     451
    355452<section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg">
    356453<t>
     
    405502  </t>
    406503</x:note>
    407 </section>
    408 </section>
    409 </section>
    410 
    411 <section title="Status Code Definitions" anchor="status.code.definitions">
    412 <section title="304 Not Modified" anchor="status.304">
    413   <iref primary="true" item="304 Not Modified (status code)" x:for-anchor=""/>
    414   <iref primary="true" item="Status Codes" subitem="304 Not Modified" x:for-anchor=""/>
    415 <t>
    416    The 304 status code indicates that a conditional GET request has been
    417    received and would have resulted in a 200 (OK) response if it were not
    418    for the fact that the condition has evaluated to false.  In other words,
    419    there is no need for the server to transfer a representation of the
    420    target resource because the client's request indicates that it already
    421    has a valid representation, as indicated by the 304 response header
    422    fields, and is therefore redirecting the client to make use of that
    423    stored representation as if it were the payload of a 200 response.
    424    The 304 response &MUST-NOT; contain a message-body, and thus is always
    425    terminated by the first empty line after the header fields.
    426 </t>
    427 <t>
    428    A 304 response &MUST; include a Date header field (&header-date;)
    429    unless its omission is required by &clockless;.  If a 200 response
    430    to the same request would have included any of the header fields
    431    Cache-Control, Content-Location, ETag, Expires, Last-Modified, or
    432    Vary, then those same header fields &MUST; be sent in a 304 response.
    433 </t>
    434 <t>
    435    Since the goal of a 304 response is to minimize information transfer
    436    when the recipient already has one or more cached representations,
    437    the response &SHOULD-NOT; include representation metadata other
    438    than the above listed fields unless said metadata exists for the
    439    purpose of guiding cache updates (e.g., future HTTP extensions).
    440 </t>
    441 <t>
    442    If the recipient of a 304 response does not have a cached representation
    443    corresponding to the entity-tag indicated by the 304 response, then the
    444    recipient &MUST-NOT; use the 304 to update its own cache.  If this
    445    conditional request originated with an outbound client, such as a
    446    user agent with its own cache sending a conditional GET to a shared
    447    proxy, then the 304 response &MAY; be forwarded to the outbound client.
    448    Otherwise, the recipient &MUST; disregard the 304 response and repeat
    449    the request without any preconditions.
    450 </t>
    451 <t>
    452    If a cache uses a received 304 response to update a cache entry, the
    453    cache &MUST; update the entry to reflect any new field values given in
    454    the response.
    455 </t>
    456 </section>
    457 
    458 <section title="412 Precondition Failed" anchor="status.412">
    459   <iref primary="true" item="412 Precondition Failed (status code)" x:for-anchor=""/>
    460   <iref primary="true" item="Status Codes" subitem="412 Precondition Failed" x:for-anchor=""/>
    461 <t>
    462    The 412 status code indicates that one or more preconditions given in
    463    the request header fields evaluated to false when tested on the server.
    464    This response code allows the client to place preconditions on the
    465    current resource state (its current representations and metadata)
    466    and thus prevent the request method from being applied if the target
    467    resource is in an unexpected state.
    468 </t>
    469504</section>
    470505</section>
     
    725760</section>
    726761
    727 <section title="Header Field Definitions" anchor="header.fields">
     762</section>
     763
     764<section title="Precondition Header Fields" anchor="header.fields">
    728765<t>
    729766   This section defines the syntax and semantics of HTTP/1.1 header fields
    730    related to conditional requests.
    731 </t>
    732 
    733 <section title="ETag" anchor="header.etag">
    734   <iref primary="true" item="ETag header field" x:for-anchor=""/>
    735   <iref primary="true" item="Header Fields" subitem="ETag" x:for-anchor=""/>
    736   <x:anchor-alias value="ETag"/>
    737 <t>
    738    The "ETag" header field provides the current value of the
    739    entity-tag (see <xref target="entity.tags"/>) for one representation of
    740    the target resource.  An entity-tag
    741    is intended for use as a resource-local identifier for differentiating
    742    between representations of the same resource that vary over time or via
    743    content negotiation (see <xref target="weak.and.strong.validators"/>).
    744 </t>
    745 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ETag"/>
    746   <x:ref>ETag</x:ref> = <x:ref>entity-tag</x:ref>
    747 </artwork></figure>
    748 <figure><preamble>
    749   Examples:
    750 </preamble>
    751 <artwork type="example">
    752   ETag: "xyzzy"
    753   ETag: W/"xyzzy"
    754   ETag: ""
    755 </artwork></figure>
    756 <t>
    757    An entity-tag provides an "opaque" cache validator that allows for
    758    more reliable validation than modification dates in situations where
    759    it is inconvenient to store modification dates,
    760    where the one-second resolution of HTTP date values is not
    761    sufficient, or where the origin server wishes to avoid certain
    762    paradoxes that might arise from the use of modification dates.
    763 </t>
    764 <t>
    765    The principle behind entity-tags is that only the service author
    766    knows the semantics of a resource well enough to select an
    767    appropriate cache validation mechanism, and the specification of any
    768    validator comparison function more complex than byte-equality would
    769    open up a can of worms. Thus, comparisons of any other header fields
    770    (except Last-Modified, for compatibility with HTTP/1.0) are never
    771    used for purposes of validating a cache entry.
    772 </t>
    773 </section>
     767   for applying preconditions on requests.
     768</t>
    774769
    775770<section title="If-Match" anchor="header.if-match">
     
    820815   The result of a request having both an If-Match header field and
    821816   either an If-None-Match or an If-Modified-Since header fields is
     817   undefined by this specification.
     818</t>
     819</section>
     820
     821<section title="If-None-Match" anchor="header.if-none-match">
     822  <iref primary="true" item="If-None-Match header field" x:for-anchor=""/>
     823  <iref primary="true" item="Header Fields" subitem="If-None-Match" x:for-anchor=""/>
     824  <x:anchor-alias value="If-None-Match"/>
     825<t>
     826   The "If-None-Match" header field &MAY; be used to make a request method
     827   conditional on not matching any of the current entity-tag values for
     828   representations of the target resource.  If-None-Match is primarily
     829   used in conditional GET requests to enable efficient updates of cached
     830   information with a minimum amount of transaction overhead.  A client
     831   that has one or more representations previously obtained from the
     832   target resource can send If-None-Match with a list of the associated
     833   entity-tags in the hope of receiving a 304 response if at least one
     834   of those representations matches the selected representation.
     835</t>
     836<t>
     837   If-None-Match MAY also be used with a value of "*" to prevent an unsafe
     838   request method (e.g., PUT) from inadvertently modifying an existing
     839   representation of the target resource when the client believes that
     840   the resource does not have a current representation.  This is a variation
     841   on the "lost update" problem that might arise if more than one client
     842   attempts to create an initial representation for the target resource.
     843</t>
     844<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-None-Match"/>
     845  <x:ref>If-None-Match</x:ref> = "*" / 1#<x:ref>entity-tag</x:ref>
     846</artwork></figure>
     847<t>
     848   If any of the entity-tags listed in the If-None-Match field-value match
     849   the entity-tag of the selected representation, or if "*" is
     850   given and any current representation exists for that resource, then the
     851   server &MUST-NOT; perform the requested method.
     852   Instead, if the request method was GET or HEAD, the server &SHOULD;
     853   respond with a 304 (Not Modified) status code, including the cache-related
     854   header fields (particularly ETag) of the selected representation that has
     855   a matching entity-tag.  For all other request methods, the server &MUST;
     856   respond with a 412 (Precondition Failed) status code.
     857</t>
     858<t>
     859   If none of the entity-tags match, then the server &MAY; perform the
     860   requested method as if the If-None-Match header field did not exist,
     861   but &MUST; also ignore any If-Modified-Since header field(s) in the
     862   request. That is, if no entity-tags match, then the server &MUST-NOT;
     863   return a 304 (Not Modified) response.
     864</t>
     865<t>
     866   If the request would, without the If-None-Match header field, result
     867   in anything other than a 2xx or 304 status code, then the If-None-Match
     868   header field &MUST; be ignored. (See <xref
     869   target="rules.for.when.to.use.entity.tags.and.last-modified.dates"/> for
     870   a discussion of server behavior when both If-Modified-Since and
     871   If-None-Match appear in the same request.)
     872</t>
     873<t>
     874   Examples:
     875</t>
     876<figure><artwork type="example">
     877  If-None-Match: "xyzzy"
     878  If-None-Match: W/"xyzzy"
     879  If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
     880  If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
     881  If-None-Match: *
     882</artwork></figure>
     883<t>
     884   The result of a request having both an If-None-Match header field and
     885   either an If-Match or an If-Unmodified-Since header fields is
    822886   undefined by this specification.
    823887</t>
     
    907971</section>
    908972
    909 <section title="If-None-Match" anchor="header.if-none-match">
    910   <iref primary="true" item="If-None-Match header field" x:for-anchor=""/>
    911   <iref primary="true" item="Header Fields" subitem="If-None-Match" x:for-anchor=""/>
    912   <x:anchor-alias value="If-None-Match"/>
    913 <t>
    914    The "If-None-Match" header field &MAY; be used to make a request method
    915    conditional on not matching any of the current entity-tag values for
    916    representations of the target resource.  If-None-Match is primarily
    917    used in conditional GET requests to enable efficient updates of cached
    918    information with a minimum amount of transaction overhead.  A client
    919    that has one or more representations previously obtained from the
    920    target resource can send If-None-Match with a list of the associated
    921    entity-tags in the hope of receiving a 304 response if at least one
    922    of those representations matches the selected representation.
    923 </t>
    924 <t>
    925    If-None-Match MAY also be used with a value of "*" to prevent an unsafe
    926    request method (e.g., PUT) from inadvertently modifying an existing
    927    representation of the target resource when the client believes that
    928    the resource does not have a current representation.  This is a variation
    929    on the "lost update" problem that might arise if more than one client
    930    attempts to create an initial representation for the target resource.
    931 </t>
    932 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-None-Match"/>
    933   <x:ref>If-None-Match</x:ref> = "*" / 1#<x:ref>entity-tag</x:ref>
    934 </artwork></figure>
    935 <t>
    936    If any of the entity-tags listed in the If-None-Match field-value match
    937    the entity-tag of the selected representation, or if "*" is
    938    given and any current representation exists for that resource, then the
    939    server &MUST-NOT; perform the requested method.
    940    Instead, if the request method was GET or HEAD, the server &SHOULD;
    941    respond with a 304 (Not Modified) status code, including the cache-related
    942    header fields (particularly ETag) of the selected representation that has
    943    a matching entity-tag.  For all other request methods, the server &MUST;
    944    respond with a 412 (Precondition Failed) status code.
    945 </t>
    946 <t>
    947    If none of the entity-tags match, then the server &MAY; perform the
    948    requested method as if the If-None-Match header field did not exist,
    949    but &MUST; also ignore any If-Modified-Since header field(s) in the
    950    request. That is, if no entity-tags match, then the server &MUST-NOT;
    951    return a 304 (Not Modified) response.
    952 </t>
    953 <t>
    954    If the request would, without the If-None-Match header field, result
    955    in anything other than a 2xx or 304 status code, then the If-None-Match
    956    header field &MUST; be ignored. (See <xref
    957    target="rules.for.when.to.use.entity.tags.and.last-modified.dates"/> for
    958    a discussion of server behavior when both If-Modified-Since and
    959    If-None-Match appear in the same request.)
    960 </t>
    961 <t>
    962    Examples:
    963 </t>
    964 <figure><artwork type="example">
    965   If-None-Match: "xyzzy"
    966   If-None-Match: W/"xyzzy"
    967   If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
    968   If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
    969   If-None-Match: *
    970 </artwork></figure>
    971 <t>
    972    The result of a request having both an If-None-Match header field and
    973    either an If-Match or an If-Unmodified-Since header fields is
    974    undefined by this specification.
    975 </t>
    976 </section>
    977 
    978973<section title="If-Unmodified-Since" anchor="header.if-unmodified-since">
    979974  <iref primary="true" item="If-Unmodified-Since header field" x:for-anchor=""/>
     
    10141009</section>
    10151010
    1016 <section title="Last-Modified" anchor="header.last-modified">
    1017   <iref primary="true" item="Last-Modified header field" x:for-anchor=""/>
    1018   <iref primary="true" item="Header Fields" subitem="Last-Modified" x:for-anchor=""/>
    1019   <x:anchor-alias value="Last-Modified"/>
    1020 <t>
    1021    The "Last-Modified" header field indicates the date and time at
    1022    which the origin server believes the representation was last modified.
    1023 </t>
    1024 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Last-Modified"/>
    1025   <x:ref>Last-Modified</x:ref> = <x:ref>HTTP-date</x:ref>
    1026 </artwork></figure>
    1027 <t>
    1028    An example of its use is
    1029 </t>
    1030 <figure><artwork type="example">
    1031   Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
    1032 </artwork></figure>
    1033 <t>
    1034    A representation is typically the sum of many parts behind the
    1035    resource interface.  The last-modified time would usually be
    1036    the most recent time that any of those parts were changed.
    1037    How that value is determined for any given resource is an
    1038    implementation detail beyond the scope of this specification.
    1039    What matters to HTTP is how recipients of the Last-Modified
    1040    header field can use its value to make conditional requests
    1041    and test the validity of locally cached responses.
    1042 </t>
    1043 <t>
    1044    An origin server &MUST-NOT; send a Last-Modified date which is later
    1045    than the server's time of message origination. In such cases, where
    1046    the resource's last modification would indicate some time in the
    1047    future, the server &MUST; replace that date with the message
    1048    origination date.
    1049 </t>
    1050 <t>
    1051    An origin server &SHOULD; obtain the Last-Modified value of the representation
    1052    as close as possible to the time that it generates the Date value of
    1053    its response. This allows a recipient to make an accurate assessment
    1054    of the representation's modification time, especially if the representation changes
    1055    near the time that the response is generated.
    1056 </t>
    1057 <t>
    1058    HTTP/1.1 servers &SHOULD; send Last-Modified whenever feasible.
    1059 </t>
    1060 <t>
    1061    The Last-Modified header field value is often used as a cache
    1062    validator. In simple terms, a cache entry is considered to be valid
    1063    if the representation has not been modified since the Last-Modified value.
    1064 </t>
    1065 </section>
    1066 
     1011</section>
     1012
     1013<section title="Status Code Definitions" anchor="status.code.definitions">
     1014<section title="304 Not Modified" anchor="status.304">
     1015  <iref primary="true" item="304 Not Modified (status code)" x:for-anchor=""/>
     1016  <iref primary="true" item="Status Codes" subitem="304 Not Modified" x:for-anchor=""/>
     1017<t>
     1018   The 304 status code indicates that a conditional GET request has been
     1019   received and would have resulted in a 200 (OK) response if it were not
     1020   for the fact that the condition has evaluated to false.  In other words,
     1021   there is no need for the server to transfer a representation of the
     1022   target resource because the client's request indicates that it already
     1023   has a valid representation, as indicated by the 304 response header
     1024   fields, and is therefore redirecting the client to make use of that
     1025   stored representation as if it were the payload of a 200 response.
     1026   The 304 response &MUST-NOT; contain a message-body, and thus is always
     1027   terminated by the first empty line after the header fields.
     1028</t>
     1029<t>
     1030   A 304 response &MUST; include a Date header field (&header-date;)
     1031   unless its omission is required by &clockless;.  If a 200 response
     1032   to the same request would have included any of the header fields
     1033   Cache-Control, Content-Location, ETag, Expires, Last-Modified, or
     1034   Vary, then those same header fields &MUST; be sent in a 304 response.
     1035</t>
     1036<t>
     1037   Since the goal of a 304 response is to minimize information transfer
     1038   when the recipient already has one or more cached representations,
     1039   the response &SHOULD-NOT; include representation metadata other
     1040   than the above listed fields unless said metadata exists for the
     1041   purpose of guiding cache updates (e.g., future HTTP extensions).
     1042</t>
     1043<t>
     1044   If the recipient of a 304 response does not have a cached representation
     1045   corresponding to the entity-tag indicated by the 304 response, then the
     1046   recipient &MUST-NOT; use the 304 to update its own cache.  If this
     1047   conditional request originated with an outbound client, such as a
     1048   user agent with its own cache sending a conditional GET to a shared
     1049   proxy, then the 304 response &MAY; be forwarded to the outbound client.
     1050   Otherwise, the recipient &MUST; disregard the 304 response and repeat
     1051   the request without any preconditions.
     1052</t>
     1053<t>
     1054   If a cache uses a received 304 response to update a cache entry, the
     1055   cache &MUST; update the entry to reflect any new field values given in
     1056   the response.
     1057</t>
     1058</section>
     1059
     1060<section title="412 Precondition Failed" anchor="status.412">
     1061  <iref primary="true" item="412 Precondition Failed (status code)" x:for-anchor=""/>
     1062  <iref primary="true" item="Status Codes" subitem="412 Precondition Failed" x:for-anchor=""/>
     1063<t>
     1064   The 412 status code indicates that one or more preconditions given in
     1065   the request header fields evaluated to false when tested on the server.
     1066   This response code allows the client to place preconditions on the
     1067   current resource state (its current representations and metadata)
     1068   and thus prevent the request method from being applied if the target
     1069   resource is in an unexpected state.
     1070</t>
     1071</section>
    10671072</section>
    10681073
Note: See TracChangeset for help on using the changeset viewer.