Ignore:
Timestamp:
06/08/11 00:59:19 (10 years ago)
Author:
fielding@…
Message:

Editorial. Move sections around without changing (much) the
text so that I can reduce more redundancy in a later commit.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r1373 r1379  
    324324</t>
    325325
    326 <section title="Last-Modified" anchor="header.last-modified">
    327   <iref primary="true" item="Last-Modified header field" x:for-anchor=""/>
    328   <iref primary="true" item="Header Fields" subitem="Last-Modified" x:for-anchor=""/>
    329   <x:anchor-alias value="Last-Modified"/>
    330 <t>
    331    The "Last-Modified" header field indicates the date and time at
    332    which the origin server believes the selected representation was
    333    last modified.
    334 </t>
    335 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Last-Modified"/>
    336   <x:ref>Last-Modified</x:ref> = <x:ref>HTTP-date</x:ref>
    337 </artwork></figure>
    338 <t>
    339    An example of its use is
    340 </t>
    341 <figure><artwork type="example">
    342   Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
    343 </artwork></figure>
    344 
    345 <section title="Generation" anchor="lastmod.generation">
    346 <t>
    347    Origin servers &SHOULD; send Last-Modified for any selected
    348    representation for which a last modification date can be reasonably
    349    and consistently determined, since its use in conditional requests
    350    and evaluating cache freshness (&caching;) results in a substantial
    351    reduction of HTTP traffic on the Internet and can be a significant
    352    factor in improving service scalability and reliability.
    353 </t>
    354 <t>
    355    A representation is typically the sum of many parts behind the
    356    resource interface.  The last-modified time would usually be
    357    the most recent time that any of those parts were changed.
    358    How that value is determined for any given resource is an
    359    implementation detail beyond the scope of this specification.
    360    What matters to HTTP is how recipients of the Last-Modified
    361    header field can use its value to make conditional requests
    362    and test the validity of locally cached responses.
    363 </t>
    364 <t>
    365    An origin server &SHOULD; obtain the Last-Modified value of the
    366    representation as close as possible to the time that it generates
    367    the Date field-value for its response. This allows a recipient to
    368    make an accurate assessment of the representation's modification time,
    369    especially if the representation changes near the time that the
    370    response is generated.
    371 </t>
    372 <t>
    373    An origin server with a clock &MUST-NOT; send a Last-Modified date
    374    that is later than the server's time of message origination (Date).
    375    If the last modification time is derived from implementation-specific
    376    metadata that evaluates to some time in the future, according to the
    377    origin server's clock, then the origin server &MUST; replace that
    378    value with the message origination date. This prevents a future
    379    modification date from having an adverse impact on cache validation.
    380 </t>
    381 </section>
    382 
    383 <section title="Comparison" anchor="lastmod.comparison">
    384 <t>
    385    A Last-Modified time, when used as a validator in a request, is
    386    implicitly weak unless it is possible to deduce that it is strong,
    387    using the following rules:
    388   <list style="symbols">
    389      <t>The validator is being compared by an origin server to the
    390         actual current validator for the representation and,</t>
    391      <t>That origin server reliably knows that the associated representation did
    392         not change twice during the second covered by the presented
    393         validator.</t>
    394   </list>
    395 </t>
    396 <t>
    397    or
    398   <list style="symbols">
    399      <t>The validator is about to be used by a client in an If-Modified-Since,
    400         If-Unmodified-Since header field, because the client has a cache entry,
    401         or If-Range for the associated representation, and</t>
    402      <t>That cache entry includes a Date value, which gives the time
    403         when the origin server sent the original response, and</t>
    404      <t>The presented Last-Modified time is at least 60 seconds before
    405         the Date value.</t>
    406   </list>
    407 </t>
    408 <t>
    409    or
    410   <list style="symbols">
    411      <t>The validator is being compared by an intermediate cache to the
    412         validator stored in its cache entry for the representation, and</t>
    413      <t>That cache entry includes a Date value, which gives the time
    414         when the origin server sent the original response, and</t>
    415      <t>The presented Last-Modified time is at least 60 seconds before
    416         the Date value.</t>
    417   </list>
    418 </t>
    419 <t>
    420    This method relies on the fact that if two different responses were
    421    sent by the origin server during the same second, but both had the
    422    same Last-Modified time, then at least one of those responses would
    423    have a Date value equal to its Last-Modified time. The arbitrary 60-second
    424    limit guards against the possibility that the Date and Last-Modified
    425    values are generated from different clocks, or at somewhat
    426    different times during the preparation of the response. An
    427    implementation &MAY; use a value larger than 60 seconds, if it is
    428    believed that 60 seconds is too short.
    429 </t>
    430 </section>
    431 </section>
    432 
    433 <section title="ETag" anchor="header.etag">
    434   <iref primary="true" item="ETag header field" x:for-anchor=""/>
    435   <iref primary="true" item="Header Fields" subitem="ETag" x:for-anchor=""/>
    436   <x:anchor-alias value="ETag"/>
    437   <x:anchor-alias value="entity-tag"/>
    438   <x:anchor-alias value="entity.tags"/>
    439   <x:anchor-alias value="opaque-tag"/>
    440   <x:anchor-alias value="weak"/>
    441 <t>
    442    The ETag header field provides the current entity-tag for the
    443    selected representation.
    444    An entity-tag is an opaque validator for differentiating between
    445    multiple representations of the same resource, regardless of whether
    446    those multiple representations are due to resource state changes over
    447    time, content negotiation resulting in multiple representations being
    448    valid at the same time, or both. An entity-tag consists of an opaque
    449    quoted string, possibly prefixed by a weakness indicator.
    450 </t>
    451 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ETag"/><iref primary="true" item="Grammar" subitem="entity-tag"/><iref primary="true" item="Grammar" subitem="weak"/><iref primary="true" item="Grammar" subitem="opaque-tag"/>
    452   <x:ref>ETag</x:ref>       = <x:ref>entity-tag</x:ref>
    453 
    454   <x:ref>entity-tag</x:ref> = [ <x:ref>weak</x:ref> ] <x:ref>opaque-tag</x:ref>
    455   <x:ref>weak</x:ref>       = <x:abnf-char-sequence>"W/"</x:abnf-char-sequence> ; "W/", case-sensitive
    456   <x:ref>opaque-tag</x:ref> = <x:ref>quoted-string</x:ref>
    457 </artwork></figure>
    458 <t>
    459    An entity-tag can be more reliable for validation than a modification
    460    date in situations where it is inconvenient to store modification
    461    dates, where the one-second resolution of HTTP date values is not
    462    sufficient, or where modification dates are not consistently maintained.
    463 </t>
    464 <figure><preamble>
    465   Examples:
    466 </preamble>
    467 <artwork type="example">
    468   ETag: "xyzzy"
    469   ETag: W/"xyzzy"
    470   ETag: ""
    471 </artwork></figure>
    472 
    473 <section title="Generation" anchor="entity.tag.generation">
    474 <t>
    475    The principle behind entity-tags is that only the service author
    476    knows the implementation of a resource well enough to select the
    477    most accurate and efficient validation mechanism for that resource,
    478    and that any such mechanism can be mapped to a simple sequence of
    479    octets for easy comparison.  Since the value is opaque, there is no
    480    need for the client to be aware of how each entity-tag is constructed.
    481 </t>
    482 <t>
    483    For example, a resource that has implementation-specific versioning
    484    applied to all changes might use an internal revision number, perhaps
    485    combined with a variance identifier for content negotiation, to
    486    accurately differentiate between representations.
    487    Other implementations might use a stored hash of representation content,
    488    a combination of various filesystem attributes, or a modification
    489    timestamp that has sub-second resolution.
    490 </t>
    491 <t>
    492    Origin servers &SHOULD; send ETag for any selected representation
    493    for which detection of changes can be reasonably and consistently
    494    determined, since the entity-tag's use in conditional requests and
    495    evaluating cache freshness (&caching;) can result in a substantial
    496    reduction of HTTP network traffic and can be a significant factor in
    497    improving service scalability and reliability.
    498 </t>
    499 </section>
    500 
    501326<section title="Weak versus Strong" anchor="weak.and.strong.validators">
    502327<t>
    … …  
    530355</t>
    531356<t>
    532    An entity-tag is normally a strong validator, but the protocol
    533    provides a mechanism to tag an entity-tag as "weak".
    534   <list><t>
    535357      A representation's modification time, if defined with only one-second
    536358      resolution, could be a weak validator, since it is possible that
    537359      the representation might be modified twice during a single second.
    538     </t><t>
     360</t><t>
    539361      Support for weak validators is optional. However, weak validators
    540362      allow for more efficient caching of equivalent objects; for
    … …  
    542364      updated every few days or weeks, and any value during that period
    543365      is likely "good enough" to be equivalent.
    544     </t></list>
    545366</t>
    546367<t>
    … …  
    570391   in use for representations of multiple resources at the same time
    571392   and does not imply that those representations are equivalent).
     393</t>
     394<t>
     395   A "use" of a validator is either when a client generates a request
     396   and includes the validator in a precondition, or when a server
     397   compares two validators.
     398</t>
     399<t>
     400   Strong validators are usable in any context. Weak validators are only
     401   usable in contexts that do not depend on exact equality of a representation.
     402   For example, either kind is usable for a normal conditional GET.
     403</t>
     404</section>
     405
     406<section title="Last-Modified" anchor="header.last-modified">
     407  <iref primary="true" item="Last-Modified header field" x:for-anchor=""/>
     408  <iref primary="true" item="Header Fields" subitem="Last-Modified" x:for-anchor=""/>
     409  <x:anchor-alias value="Last-Modified"/>
     410<t>
     411   The "Last-Modified" header field indicates the date and time at
     412   which the origin server believes the selected representation was
     413   last modified.
     414</t>
     415<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Last-Modified"/>
     416  <x:ref>Last-Modified</x:ref> = <x:ref>HTTP-date</x:ref>
     417</artwork></figure>
     418<t>
     419   An example of its use is
     420</t>
     421<figure><artwork type="example">
     422  Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
     423</artwork></figure>
     424
     425<section title="Generation" anchor="lastmod.generation">
     426<t>
     427   Origin servers &SHOULD; send Last-Modified for any selected
     428   representation for which a last modification date can be reasonably
     429   and consistently determined, since its use in conditional requests
     430   and evaluating cache freshness (&caching;) results in a substantial
     431   reduction of HTTP traffic on the Internet and can be a significant
     432   factor in improving service scalability and reliability.
     433</t>
     434<t>
     435   A representation is typically the sum of many parts behind the
     436   resource interface.  The last-modified time would usually be
     437   the most recent time that any of those parts were changed.
     438   How that value is determined for any given resource is an
     439   implementation detail beyond the scope of this specification.
     440   What matters to HTTP is how recipients of the Last-Modified
     441   header field can use its value to make conditional requests
     442   and test the validity of locally cached responses.
     443</t>
     444<t>
     445   An origin server &SHOULD; obtain the Last-Modified value of the
     446   representation as close as possible to the time that it generates
     447   the Date field-value for its response. This allows a recipient to
     448   make an accurate assessment of the representation's modification time,
     449   especially if the representation changes near the time that the
     450   response is generated.
     451</t>
     452<t>
     453   An origin server with a clock &MUST-NOT; send a Last-Modified date
     454   that is later than the server's time of message origination (Date).
     455   If the last modification time is derived from implementation-specific
     456   metadata that evaluates to some time in the future, according to the
     457   origin server's clock, then the origin server &MUST; replace that
     458   value with the message origination date. This prevents a future
     459   modification date from having an adverse impact on cache validation.
     460</t>
     461</section>
     462
     463<section title="Comparison" anchor="lastmod.comparison">
     464<t>
     465   A Last-Modified time, when used as a validator in a request, is
     466   implicitly weak unless it is possible to deduce that it is strong,
     467   using the following rules:
     468  <list style="symbols">
     469     <t>The validator is being compared by an origin server to the
     470        actual current validator for the representation and,</t>
     471     <t>That origin server reliably knows that the associated representation did
     472        not change twice during the second covered by the presented
     473        validator.</t>
     474  </list>
     475</t>
     476<t>
     477   or
     478  <list style="symbols">
     479     <t>The validator is about to be used by a client in an If-Modified-Since,
     480        If-Unmodified-Since header field, because the client has a cache entry,
     481        or If-Range for the associated representation, and</t>
     482     <t>That cache entry includes a Date value, which gives the time
     483        when the origin server sent the original response, and</t>
     484     <t>The presented Last-Modified time is at least 60 seconds before
     485        the Date value.</t>
     486  </list>
     487</t>
     488<t>
     489   or
     490  <list style="symbols">
     491     <t>The validator is being compared by an intermediate cache to the
     492        validator stored in its cache entry for the representation, and</t>
     493     <t>That cache entry includes a Date value, which gives the time
     494        when the origin server sent the original response, and</t>
     495     <t>The presented Last-Modified time is at least 60 seconds before
     496        the Date value.</t>
     497  </list>
     498</t>
     499<t>
     500   This method relies on the fact that if two different responses were
     501   sent by the origin server during the same second, but both had the
     502   same Last-Modified time, then at least one of those responses would
     503   have a Date value equal to its Last-Modified time. The arbitrary 60-second
     504   limit guards against the possibility that the Date and Last-Modified
     505   values are generated from different clocks, or at somewhat
     506   different times during the preparation of the response. An
     507   implementation &MAY; use a value larger than 60 seconds, if it is
     508   believed that 60 seconds is too short.
     509</t>
     510</section>
     511</section>
     512
     513<section title="ETag" anchor="header.etag">
     514  <iref primary="true" item="ETag header field" x:for-anchor=""/>
     515  <iref primary="true" item="Header Fields" subitem="ETag" x:for-anchor=""/>
     516  <x:anchor-alias value="ETag"/>
     517  <x:anchor-alias value="entity-tag"/>
     518  <x:anchor-alias value="entity.tags"/>
     519  <x:anchor-alias value="opaque-tag"/>
     520  <x:anchor-alias value="weak"/>
     521<t>
     522   The ETag header field provides the current entity-tag for the
     523   selected representation.
     524   An entity-tag is an opaque validator for differentiating between
     525   multiple representations of the same resource, regardless of whether
     526   those multiple representations are due to resource state changes over
     527   time, content negotiation resulting in multiple representations being
     528   valid at the same time, or both. An entity-tag consists of an opaque
     529   quoted string, possibly prefixed by a weakness indicator.
     530</t>
     531<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ETag"/><iref primary="true" item="Grammar" subitem="entity-tag"/><iref primary="true" item="Grammar" subitem="weak"/><iref primary="true" item="Grammar" subitem="opaque-tag"/>
     532  <x:ref>ETag</x:ref>       = <x:ref>entity-tag</x:ref>
     533
     534  <x:ref>entity-tag</x:ref> = [ <x:ref>weak</x:ref> ] <x:ref>opaque-tag</x:ref>
     535  <x:ref>weak</x:ref>       = <x:abnf-char-sequence>"W/"</x:abnf-char-sequence> ; "W/", case-sensitive
     536  <x:ref>opaque-tag</x:ref> = <x:ref>quoted-string</x:ref>
     537</artwork></figure>
     538<t>
     539   An entity-tag can be more reliable for validation than a modification
     540   date in situations where it is inconvenient to store modification
     541   dates, where the one-second resolution of HTTP date values is not
     542   sufficient, or where modification dates are not consistently maintained.
     543</t>
     544<figure><preamble>
     545  Examples:
     546</preamble>
     547<artwork type="example">
     548  ETag: "xyzzy"
     549  ETag: W/"xyzzy"
     550  ETag: ""
     551</artwork></figure>
     552<t>
     553   An entity-tag can be either a weak or strong validator, with
     554   strong being the default.  If an origin server provides an entity-tag
     555   for a representation and the generation of that entity-tag does not satisfy
     556   the requirements for a strong validator
     557   (<xref target="weak.and.strong.validators"/>), then that
     558   entity-tag &MUST; be marked as weak by prefixing its opaque value
     559   with "W/" (case-sensitive).
     560</t>
     561
     562<section title="Generation" anchor="entity.tag.generation">
     563<t>
     564   The principle behind entity-tags is that only the service author
     565   knows the implementation of a resource well enough to select the
     566   most accurate and efficient validation mechanism for that resource,
     567   and that any such mechanism can be mapped to a simple sequence of
     568   octets for easy comparison.  Since the value is opaque, there is no
     569   need for the client to be aware of how each entity-tag is constructed.
     570</t>
     571<t>
     572   For example, a resource that has implementation-specific versioning
     573   applied to all changes might use an internal revision number, perhaps
     574   combined with a variance identifier for content negotiation, to
     575   accurately differentiate between representations.
     576   Other implementations might use a stored hash of representation content,
     577   a combination of various filesystem attributes, or a modification
     578   timestamp that has sub-second resolution.
     579</t>
     580<t>
     581   Origin servers &SHOULD; send ETag for any selected representation
     582   for which detection of changes can be reasonably and consistently
     583   determined, since the entity-tag's use in conditional requests and
     584   evaluating cache freshness (&caching;) can result in a substantial
     585   reduction of HTTP network traffic and can be a significant factor in
     586   improving service scalability and reliability.
    572587</t>
    573588</section>
    … …  
    590605</t>
    591606<t>
    592    A "use" of a validator is either when a client generates a request
    593    and includes the validator in a precondition, or when a server
    594    compares two validators.
    595 </t>
    596 <t>
    597    Strong validators are usable in any context. Weak validators are only
    598    usable in contexts that do not depend on exact equality of a representation.
    599    For example, either kind is usable for a normal conditional GET.
    600 </t>
    601 <t>
    602607   The example below shows the results for a set of entity-tag pairs,
    603608   and both the weak and strong comparison function results:
    … …  
    629634  <c>match</c>
    630635</texttable>
    631 <t>
    632    An entity-tag is strong unless it is explicitly tagged as weak.
    633 </t>
     636</section>
     637
     638<section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg">
     639<t>
     640   Consider a resource that is subject to content negotiation (&content-negotiation;),
     641   and where the representations returned upon a GET request vary based on
     642   the Accept-Encoding request header field (&header-accept-encoding;):
     643</t>
     644<figure><preamble>>> Request:</preamble><artwork type="message/http; msgtype=&#34;request&#34;"  x:indent-with="  ">
     645GET /index HTTP/1.1
     646Host: www.example.com
     647Accept-Encoding: gzip
     648
     649</artwork></figure>
     650<t>
     651   In this case, the response might or might not use the gzip content coding.
     652   If it does not, the response might look like:
     653</t>
     654<figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype=&#34;response&#34;"  x:indent-with="  ">
     655HTTP/1.1 200 OK
     656Date: Thu, 26 Mar 2010 00:05:00 GMT
     657ETag: "123-a"
     658Content-Length: <x:length-of target="exbody"/>
     659Vary: Accept-Encoding
     660Content-Type: text/plain
     661
     662<x:span anchor="exbody">Hello World!
     663Hello World!
     664Hello World!
     665Hello World!
     666Hello World!
     667</x:span></artwork></figure>
     668<t>
     669   An alternative representation that does use gzip content coding would be:
     670</t>
     671<figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype=&#34;response&#34;"  x:indent-with="  ">
     672HTTP/1.1 200 OK
     673Date: Thu, 26 Mar 2010 00:05:00 GMT
     674ETag: "123-b"
     675Content-Length: 43
     676Vary: Accept-Encoding
     677Content-Type: text/plain
     678Content-Encoding: gzip
     679
     680<spanx>...binary data...</spanx></artwork></figure>
     681<x:note>
     682  <t>
     683    <x:h>Note:</x:h> Content codings are a property of the representation,
     684    so therefore an entity-tag of an encoded representation must be distinct
     685    from an unencoded representation to prevent conflicts during cache updates
     686    and range requests.  In contrast, transfer codings (&transfer-codings;)
     687    apply only during message transfer and do not require distinct entity-tags.
     688  </t>
     689</x:note>
     690</section>
    634691</section>
    635692
    … …  
    712769</section>
    713770
    714 <section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg">
    715 <t>
    716    Consider a resource that is subject to content negotiation (&content-negotiation;),
    717    and where the representations returned upon a GET request vary based on
    718    the Accept-Encoding request header field (&header-accept-encoding;):
    719 </t>
    720 <figure><preamble>>> Request:</preamble><artwork type="message/http; msgtype=&#34;request&#34;"  x:indent-with="  ">
    721 GET /index HTTP/1.1
    722 Host: www.example.com
    723 Accept-Encoding: gzip
    724 
    725 </artwork></figure>
    726 <t>
    727    In this case, the response might or might not use the gzip content coding.
    728    If it does not, the response might look like:
    729 </t>
    730 <figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype=&#34;response&#34;"  x:indent-with="  ">
    731 HTTP/1.1 200 OK
    732 Date: Thu, 26 Mar 2010 00:05:00 GMT
    733 ETag: "123-a"
    734 Content-Length: <x:length-of target="exbody"/>
    735 Vary: Accept-Encoding
    736 Content-Type: text/plain
    737 
    738 <x:span anchor="exbody">Hello World!
    739 Hello World!
    740 Hello World!
    741 Hello World!
    742 Hello World!
    743 </x:span></artwork></figure>
    744 <t>
    745    An alternative representation that does use gzip content coding would be:
    746 </t>
    747 <figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype=&#34;response&#34;"  x:indent-with="  ">
    748 HTTP/1.1 200 OK
    749 Date: Thu, 26 Mar 2010 00:05:00 GMT
    750 ETag: "123-b"
    751 Content-Length: 43
    752 Vary: Accept-Encoding
    753 Content-Type: text/plain
    754 Content-Encoding: gzip
    755 
    756 <spanx>...binary data...</spanx></artwork></figure>
    757 <x:note>
    758   <t>
    759     <x:h>Note:</x:h> Content codings are a property of the representation,
    760     so therefore an entity-tag of an encoded representation must be distinct
    761     from an unencoded representation to prevent conflicts during cache updates
    762     and range requests.  In contrast, transfer codings (&transfer-codings;)
    763     apply only during message transfer and do not require distinct entity-tags.
    764   </t>
    765 </x:note>
    766 </section>
    767 </section>
    768771</section>
    769772
Note: See TracChangeset for help on using the changeset viewer.