Ignore:
Timestamp:
Mar 28, 2011, 7:15:02 AM (9 years ago)
Author:
fielding@…
Message:

Define "selected representation" as a shorthand for targeting
conditional requests, effectively replacing the old notion
of resource variants. Addresses #89.

Remove the nonsense about semantic equivalence and replace it
with the mechanical reason that origin servers might not want
to change a weak entity-tag on every update. Addresses #101.

Rewrite the condtional evaluation text accordingly and reduce
some duplication of requirements.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • draft-ietf-httpbis/latest/p4-conditional.xml

    r1180 r1223  
    225225</t>
    226226<t>
     227   We use the term "selected representation" to refer to the current
     228   representation of the target resource that would have been selected
     229   and sent as payload in a 200 (OK) response if the same request had used
     230   the method GET and had excluded all of the conditional request header
     231   fields.  The conditions found within conditional requests are evaluated
     232   on the basis of either the state of the target resource as a whole or
     233   the state of the target resource's selected representation.
     234</t>
     235<t>
    227236   This document is currently disorganized in order to minimize the changes
    228237   between drafts and enable reviewers to see the smaller errata changes.
    … …  
    329338<t>
    330339   A "weak entity-tag", indicated by the "W/" prefix, &MAY; be shared by
    331    two representations of a resource only if the representations are equivalent and
    332    could be substituted for each other with no significant change in
    333    semantics. A weak entity-tag can only be used for weak comparison.
    334 </t>
    335 <t>
    336    An entity-tag &MUST; be unique across all versions of all representations
    337    associated with a particular resource. A given entity-tag value &MAY;
    338    be used for representations obtained by requests on different URIs. The use
    339    of the same entity-tag value in conjunction with representations obtained by
    340    requests on different URIs does not imply the equivalence of those
    341    representations.
     340   two representations of a resource. A weak entity-tag can only be used
     341   for weak comparison.
     342</t>
     343<t>
     344   Cache entries might persist for arbitrarily long periods, regardless
     345   of expiration times, so it is inappropriate to expect that a cache will
     346   never again attempt to validate an entry using a validator that it
     347   obtained at some point in the past.
     348   A strong entity-tag &MUST; be unique across all versions of all
     349   representations associated with a particular resource over time.
     350   However, there is no implication of uniqueness across entity-tags
     351   of different resources (i.e., the same entity-tag value might be
     352   in use for representations of multiple resources at the same time
     353   and does not imply that those representations are equivalent).
    342354</t>
    343355
    … …  
    402414  <iref primary="true" item="Status Codes" subitem="304 Not Modified" x:for-anchor=""/>
    403415<t>
    404    If the client has performed a conditional GET request and access is
    405    allowed, but the document has not been modified, the server &SHOULD;
    406    respond with this status code. The 304 response &MUST-NOT; contain a
    407    message-body, and thus is always terminated by the first empty line
    408    after the header fields.
     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.
    409426</t>
    410427<t>
    … …  
    423440</t>
    424441<t>
    425    If a 304 response includes an entity-tag that indicates a
    426    representation not currently cached, then the recipient &MUST-NOT;
    427    use the 304 to update its own cache.  If that conditional request originated
    428    with an outbound client, such as a user agent with its own cache sending a
    429    conditional GET to a shared proxy, then the 304 response &MAY; be
    430    forwarded to the outbound client.  Otherwise, disregard the response
    431    and repeat the request without the conditional.
     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.
    432450</t>
    433451<t>
    … …  
    442460  <iref primary="true" item="Status Codes" subitem="412 Precondition Failed" x:for-anchor=""/>
    443461<t>
    444    The precondition given in one or more of the header fields
    445    evaluated to false when it was tested on the server. This response
    446    code allows the client to place preconditions on the current resource
    447    metadata (header field data) and thus prevent the requested
    448    method from being applied to a resource other than the one intended.
     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.
    449468</t>
    450469</section>
    … …  
    454473<t>
    455474   Since both origin servers and caches will compare two validators to
    456    decide if they represent the same or different representations, one normally
    457    would expect that if the representation (including both representation
    458    header fields and representation body) changes in any way, then the
    459    associated validator would change as well. If this is true, then we
    460    call this validator a "strong validator".
     475   decide if they represent the same or different representations, one
     476   normally would expect that if the representation (including both
     477   representation header fields and representation body) changes in any
     478   way, then the associated validator would change as well. If this is
     479   true, then we call this validator a "strong validator".  One example
     480   of a strong validator is an integer that is incremented in stable
     481   storage every time a representation is changed.
    461482</t>
    462483<t>
    463484   However, there might be cases when a server prefers to change the
    464    validator only on semantically significant changes, and not when
    465    insignificant aspects of the representation change. A validator that does not
    466    always change when the representation changes is a "weak validator".
     485   validator only when it desires cached representations to be invalidated.
     486   For example, the representation of a weather report that changes in
     487   content every second, based on dynamic measurements, might be grouped
     488   into sets of equivalent representations (from the origin server's
     489   perspective) in order to allow cached representations to be valid
     490   for a reasonable period of time (perhaps adjusted dynamically based
     491   on server load or weather quality).
     492   A validator that does not always change when the representation
     493   changes is a "weak validator".
    467494</t>
    468495<t>
    469496   An entity-tag is normally a strong validator, but the protocol
    470    provides a mechanism to tag an entity-tag as "weak". One can think of
    471    a strong validator as one that changes whenever the sequence of bits
    472    in a representation changes, while a weak value changes whenever the
    473    meaning of a representation changes. Alternatively, one can think of
    474    a strong validator as part of an identifier for a specific representation,
    475    whereas a weak validator is part of an identifier for a set of semantically
    476    equivalent representations.
     497   provides a mechanism to tag an entity-tag as "weak". One can think
     498   of a strong validator as part of an identifier for a specific
     499   representation, whereas a weak validator is part of an identifier
     500   for a set of equivalent representations (where this notion of
     501   equivalence is entirely governed by the origin server and beyond
     502   the scope of this specification).
    477503  <list><t>
    478       <x:h>Note:</x:h> One example of a strong validator is an integer that is
    479       incremented in stable storage every time a representation is changed.
    480     </t><t>
    481504      A representation's modification time, if defined with only one-second
    482505      resolution, could be a weak validator, since it is possible that
    … …  
    491514</t>
    492515<t>
     516   A strong entity-tag &MUST; change whenever the associated representation
     517   changes in any way. A weak entity-tag &SHOULD; change whenever the origin
     518   server considers prior representations to be unacceptable as a substitute
     519   for the current representation. In other words, a weak entity tag &SHOULD;
     520   change whenever the origin server wants caches to invalidate old responses.
     521</t>
     522<t>
    493523   A "use" of a validator is either when a client generates a request
    494524   and includes the validator in a validating header field, or when a
    … …  
    499529   usable in contexts that do not depend on exact equality of a representation.
    500530   For example, either kind is usable for a normal conditional GET.
    501    However, only a strong validator is usable for a sub-range
    502    retrieval, since otherwise the client might end up with an internally
    503    inconsistent representation.
    504 </t>
    505 <t>
    506    Clients &MUST-NOT; use weak validators in range requests (<xref target="Part5"/>).
     531   However, only a strong validator is usable for range retrieval
     532   (<xref target="Part5"/>), since otherwise the client might end up
     533   with an internally inconsistent representation.
     534   Clients &MUST-NOT; use weak validators in range requests.
    507535</t>
    508536<t>
    … …  
    635663        or if it is unfeasible to send a strong entity-tag.</t>
    636664
    637      <t>&SHOULD; send a Last-Modified value if it is feasible to send one,
    638         unless the risk of a breakdown in semantic transparency that
    639         could result from using this date in an If-Modified-Since header
    640         field would lead to serious problems.</t>
     665     <t>&SHOULD; send a Last-Modified value if it is feasible to send one.</t>
    641666  </list>
    642667</t>
    … …  
    645670   is to send both a strong entity-tag and a Last-Modified value.
    646671</t>
    647 <t>
    648    In order to be legitimate, a strong entity-tag &MUST; change whenever the
    649    associated representation changes in any way. A weak entity-tag &SHOULD;
    650    change whenever the associated representation changes in a semantically
    651    significant way.
    652 </t>
    653 <x:note>
    654   <t>
    655     <x:h>Note:</x:h> In order to provide semantically transparent caching, an
    656     origin server must avoid reusing a specific strong entity-tag
    657     value for two different representations, or reusing a specific weak
    658     entity-tag value for two semantically different representations. Cache
    659     entries might persist for arbitrarily long periods, regardless of
    660     expiration times, so it might be inappropriate to expect that a
    661     cache will never again attempt to validate an entry using a
    662     validator that it obtained at some point in the past.
    663   </t>
    664 </x:note>
    665672<t>
    666673   HTTP/1.1 clients:
    … …  
    774781  <x:anchor-alias value="If-Match-v"/>
    775782<t>
    776    The "If-Match" header field is used to make a request method
    777    conditional. A client that has one or more representations previously
    778    obtained from the resource can verify that one of those representations is
    779    current by including a list of their associated entity-tags in the
    780    If-Match header field.
    781 </t>
    782 <t>
    783    This allows efficient updates of cached information with a minimum amount of
    784    transaction overhead. It is also used when updating resources, to prevent
    785    inadvertent modification of the wrong version of a resource. As a special
    786    case, the value "*" matches any current representation of the resource.
     783   The "If-Match" header field &MAY; be used to make a request method
     784   conditional on the current existence or value of an entity-tag for
     785   one or more representations of the target resource.  If-Match is
     786   generally useful for resource update requests, such as PUT requests,
     787   as a means for protecting against accidental overwrites when multiple
     788   clients are acting in parallel on the same resource (i.e., the
     789   "lost update" problem).  An If-Match field-value of "*" places the
     790   precondition on the existence of any current representation for the
     791   target resource.
    787792</t>
    788793<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Match"/><iref primary="true" item="Grammar" subitem="If-Match-v"/>
    … …  
    791796</artwork></figure>
    792797<t>
    793    If any of the entity-tags match the entity-tag of the representation that
    794    would have been returned in the response to a similar GET request
    795    (without the If-Match header field) on that resource, or if "*" is given
    796    and any current representation exists for that resource, then the server &MAY;
    797    perform the requested method as if the If-Match header field did not
    798    exist.
     798   If any of the entity-tags listed in the If-Match field value match
     799   the entity-tag of the selected representation for the target resource,
     800   or if "*" is given and any current representation exists for the
     801   target resource, then the server &MAY; perform the request method
     802   as if the If-Match header field was not present.
    799803</t>
    800804<t>
    801805   If none of the entity-tags match, or if "*" is given and no current
    802    representation exists, the server &MUST-NOT; perform the requested method, and
    803    &MUST; return a 412 (Precondition Failed) response. This behavior is
    804    most useful when the client wants to prevent an updating request method,
    805    such as PUT, from modifying a resource that has changed since the client
    806    last retrieved it.
     806   representation exists, the server &MUST-NOT; perform the requested method.
     807   Instead, the server &MUST; respond with the 412 (Precondition Failed)
     808   status code.
    807809</t>
    808810<t>
    … …  
    812814</t>
    813815<t>
    814    The meaning of "If-Match: *" is that the request method &SHOULD; be performed
    815    if the representation selected by the origin server (or by a cache,
    816    possibly using the Vary mechanism, see &header-vary;) exists, and
    817    &MUST-NOT; be performed if the representation does not exist.
    818 </t>
    819 <t>
    820    A request intended to update a resource (e.g., a PUT) &MAY; include an
    821    If-Match header field to signal that the request method &MUST-NOT; be
    822    applied if the representation corresponding to the If-Match value (a single
    823    entity-tag) is no longer a representation of that resource. This
    824    allows the user to indicate that they do not wish the request to be
    825    successful if the resource has been changed without their knowledge.
    826816   Examples:
    827817</t>
    … …  
    844834  <x:anchor-alias value="If-Modified-Since-v"/>
    845835<t>
    846    The "If-Modified-Since" header field is used to make a request
    847    method conditional by date: if the representation that would have been
    848    transferred in a 200 response to a GET request has not been modified since
    849    the time specified in this field, then do not perform the method;
    850    instead, respond as detailed below.
     836   The "If-Modified-Since" header field &MAY; be used to make a request
     837   method conditional by modification date: if the selected representation
     838   has not been modified since the time specified in this field, then
     839   do not perform the request method; instead, respond as detailed below.
    851840</t>
    852841<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Modified-Since"/><iref primary="true" item="Grammar" subitem="If-Modified-Since-v"/>
    … …  
    863852<t>
    864853   A GET method with an If-Modified-Since header field and no Range header
    865    field requests that the representation be transferred only if it has
    866    been modified since the date given by the If-Modified-Since header field.
     854   field requests that the selected representation be transferred only if
     855   it has been modified since the date given by the If-Modified-Since
     856   header field.
    867857   The algorithm for determining this includes the following cases:
    868858  <list style="numbers">
    … …  
    873863         invalid.</t>
    874864
    875       <t>If the representation has been modified since the If-Modified-Since
    876          date, the response is exactly the same as for a normal GET.</t>
    877 
    878       <t>If the representation has not been modified since a valid
     865      <t>If the selected representation has been modified since the
     866         If-Modified-Since date, the response is exactly the same as for
     867         a normal GET.</t>
     868
     869      <t>If the selected representation has not been modified since a valid
    879870         If-Modified-Since date, the server &SHOULD; return a
    880871         304 (Not Modified) response.</t>
    … …  
    929920  <x:anchor-alias value="If-None-Match-v"/>
    930921<t>
    931    The "If-None-Match" header field is used to make a request method
    932    conditional. A client that has one or more representations previously
    933    obtained from the resource can verify that none of those representations is
    934    current by including a list of their associated entity-tags in the
    935    If-None-Match header field.
    936 </t>
    937 <t>
    938    This allows efficient updates of cached information with a minimum amount of
    939    transaction overhead. It is also used to prevent a request method (e.g., PUT)
    940    from inadvertently modifying an existing resource when the client
    941    believes that the resource does not exist.
    942 </t>
    943 <t>
    944    As a special case, the value "*" matches any current representation of the
    945    resource.
     922   The "If-None-Match" header field &MAY; be used to make a request method
     923   conditional on not matching any of the current entity-tag values for
     924   representations of the target resource.  If-None-Match is primarily
     925   used in conditional GET requests to enable efficient updates of cached
     926   information with a minimum amount of transaction overhead.  A client
     927   that has one or more representations previously obtained from the
     928   target resource can send If-None-Match with a list of the associated
     929   entity-tags in the hope of receiving a 304 response if at least one
     930   of those representations matches the selected representation.
     931</t>
     932<t>
     933   If-None-Match MAY also be used with a value of "*" to prevent an unsafe
     934   request method (e.g., PUT) from inadvertently modifying an existing
     935   representation of the target resource when the client believes that
     936   the resource does not have a current representation.  This is a variation
     937   on the "lost update" problem that might arise if more than one client
     938   attempts to create an initial representation for the target resource.
    946939</t>
    947940<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-None-Match"/><iref primary="true" item="Grammar" subitem="If-None-Match-v"/>
    … …  
    950943</artwork></figure>
    951944<t>
    952    If any of the entity-tags match the entity-tag of the representation that
    953    would have been returned in the response to a similar GET request
    954    (without the If-None-Match header field) on that resource, or if "*" is
     945   If any of the entity-tags listed in the If-None-Match field-value match
     946   the entity-tag of the selected representation, or if "*" is
    955947   given and any current representation exists for that resource, then the
    956    server &MUST-NOT; perform the requested method, unless required to do
    957    so because the resource's modification date fails to match that
    958    supplied in an If-Modified-Since header field in the request.
     948   server &MUST-NOT; perform the requested method.
    959949   Instead, if the request method was GET or HEAD, the server &SHOULD;
    960    respond with a 304 (Not Modified) response, including the cache-related
    961    header fields (particularly ETag) of one of the representations that
    962    matched. For all other request methods, the server &MUST; respond with
    963    a 412 (Precondition Failed) status code.
     950   respond with a 304 (Not Modified) status code, including the cache-related
     951   header fields (particularly ETag) of the selected representation that has
     952   a matching entity-tag.  For all other request methods, the server &MUST;
     953   respond with a 412 (Precondition Failed) status code.
    964954</t>
    965955<t>
    … …  
    973963   If the request would, without the If-None-Match header field, result
    974964   in anything other than a 2xx or 304 status code, then the If-None-Match
    975    header field &MUST; be ignored. (See <xref target="rules.for.when.to.use.entity.tags.and.last-modified.dates"/> for a discussion of
    976    server behavior when both If-Modified-Since and If-None-Match appear
    977    in the same request.)
    978 </t>
    979 <t>
    980    The meaning of "If-None-Match: *" is that the request method &MUST-NOT; be
    981    performed if the representation selected by the origin server (or by
    982    a cache, possibly using the Vary mechanism, see &header-vary;)
    983    exists, and &SHOULD; be performed if the representation does not exist.
    984    This feature is intended to be useful in preventing races between PUT
    985    operations.
     965   header field &MUST; be ignored. (See <xref
     966   target="rules.for.when.to.use.entity.tags.and.last-modified.dates"/> for
     967   a discussion of server behavior when both If-Modified-Since and
     968   If-None-Match appear in the same request.)
    986969</t>
    987970<t>
    … …  
    1008991  <x:anchor-alias value="If-Unmodified-Since-v"/>
    1009992<t>
    1010    The "If-Unmodified-Since" header field is used to make a request
    1011    method conditional.  If the representation that would have been transferred
    1012    in a 200 response to a GET request on the same resource has not been modified
    1013    since the time specified in this field, the server &SHOULD; perform the
    1014    requested operation as if the If-Unmodified-Since header field were not
    1015    present.
    1016 </t>
    1017 <t>
    1018    If the representation has been modified since the specified time,
    1019    the server &MUST-NOT; perform the requested operation, and &MUST; return
    1020    a 412 (Precondition Failed).
     993   The "If-Unmodified-Since" header field &MAY; be used to make a request
     994   method conditional by modification date: if the selected representation
     995   has been modified since the time specified in this field, then the
     996   server &MUST-NOT; perform the requested operation and &MUST; instead
     997   respond with the 412 (Precondition Failed) status code.
     998   If the selected representation has not been modified since the time
     999   specified in this field, the server &SHOULD; perform the request
     1000   method as if the If-Unmodified-Since header field were not present.
    10211001</t>
    10221002<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Unmodified-Since"/><iref primary="true" item="Grammar" subitem="If-Unmodified-Since-v"/>
    … …  
    10371017</t>
    10381018<t>
    1039    If the specified date is invalid, the header field is ignored.
     1019   If the specified date is invalid, the header field &MUST; be ignored.
    10401020</t>
    10411021<t>
Note: See TracChangeset for help on using the changeset viewer.