Ignore:
Timestamp:
13/09/13 13:09:58 (7 years ago)
Author:
julian.reschke@…
Message:

enhance consistency in header field descriptions (see #495)

Location:
draft-ietf-httpbis/latest
Files:
2 edited

Legend:

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

    r2381 r2387  
    939939      <p id="rfc.section.3.1.p.1">The "If-Match" header field makes the request method conditional on the recipient cache or origin server either having at
    940940         least one current representation of the target resource, when the field-value is "*", or having a current representation of
    941          the target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value. A recipient <em class="bcp14">MUST</em> use the strong comparison function when comparing entity-tags for If-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
     941         the target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value.
     942      </p>
     943      <p id="rfc.section.3.1.p.2">A recipient <em class="bcp14">MUST</em> use the strong comparison function when comparing entity-tags for If-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
    942944      </p>
    943945      <div id="rfc.figure.u.8"></div><pre class="inline"><span id="rfc.iref.g.7"></span>  <a href="#header.if-match" class="smpl">If-Match</a> = "*" / 1#<a href="#header.etag" class="smpl">entity-tag</a>
    944 </pre><p id="rfc.section.3.1.p.3">Examples:</p>
     946</pre><p id="rfc.section.3.1.p.4">Examples:</p>
    945947      <div id="rfc.figure.u.9"></div><pre class="text">  If-Match: "xyzzy"
    946948  If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
    947949  If-Match: *
    948 </pre><p id="rfc.section.3.1.p.5">If-Match is most often used with state-changing methods (e.g., POST, PUT, DELETE) to prevent accidental overwrites when multiple
     950</pre><p id="rfc.section.3.1.p.6">If-Match is most often used with state-changing methods (e.g., POST, PUT, DELETE) to prevent accidental overwrites when multiple
    949951         user agents might be acting in parallel on the same resource (i.e., to prevent the "lost update" problem). It can also be
    950952         used with safe methods to abort a request if the <a href="p2-semantics.html#representations" class="smpl">selected representation</a> does not match one already stored (or partially stored) from a prior request.
    951953      </p>
    952       <p id="rfc.section.3.1.p.6">An origin server that receives an If-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server does not have a current representation for the target
     954      <p id="rfc.section.3.1.p.7">An origin server that receives an If-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server does not have a current representation for the target
    953955         resource. If the field-value is a list of entity-tags, the condition is false if none of the listed tags match the entity-tag
    954956         of the selected representation.
    955957      </p>
    956       <p id="rfc.section.3.1.p.7">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if a received If-Match condition evaluates to false; instead the origin server <em class="bcp14">MUST</em> respond with either: a) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code; or, b) one of the <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> status codes if the origin server has verified that a state change is being requested and the final state is already reflected
     958      <p id="rfc.section.3.1.p.8">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if a received If-Match condition evaluates to false; instead the origin server <em class="bcp14">MUST</em> respond with either: a) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code; or, b) one of the <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> status codes if the origin server has verified that a state change is being requested and the final state is already reflected
    957959         in the current state of the target resource (i.e., the change requested by the user agent has already succeeded, but the user
    958960         agent might not be aware of it, perhaps because the prior response was lost or a compatible change was made by some other
     
    963965      <h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a>&nbsp;<a id="header.if-none-match" href="#header.if-none-match">If-None-Match</a></h2>
    964966      <p id="rfc.section.3.2.p.1">The "If-None-Match" header field makes the request method conditional on the recipient cache or origin server either not having
    965          a current representation for the target resource, when the field-value is "*", or not having a current representation that
    966          has an entity-tag matching a member of the list of entity-tags provided in the field-value. A recipient <em class="bcp14">MUST</em> use the weak comparison function when comparing entity-tags for If-None-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
     967         a current representation of the target resource, when the field-value is "*", or not having a current representation of the
     968         target resource that has an entity-tag matching a member of the list of entity-tags provided in the field-value.
     969      </p>
     970      <p id="rfc.section.3.2.p.2">A recipient <em class="bcp14">MUST</em> use the weak comparison function when comparing entity-tags for If-None-Match (<a href="#entity.tag.comparison" title="Comparison">Section&nbsp;2.3.2</a>).
    967971      </p>
    968972      <div id="rfc.figure.u.10"></div><pre class="inline"><span id="rfc.iref.g.8"></span>  <a href="#header.if-none-match" class="smpl">If-None-Match</a> = "*" / 1#<a href="#header.etag" class="smpl">entity-tag</a>
    969 </pre><p id="rfc.section.3.2.p.3">Examples:</p>
     973</pre><p id="rfc.section.3.2.p.4">Examples:</p>
    970974      <div id="rfc.figure.u.11"></div><pre class="text">  If-None-Match: "xyzzy"
    971975  If-None-Match: W/"xyzzy"
     
    973977  If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
    974978  If-None-Match: *
    975 </pre><p id="rfc.section.3.2.p.5">If-None-Match is primarily used in conditional GET requests to enable efficient updates of cached information with a minimum
     979</pre><p id="rfc.section.3.2.p.6">If-None-Match is primarily used in conditional GET requests to enable efficient updates of cached information with a minimum
    976980         amount of transaction overhead. When a client desires to update one or more stored responses that have entity-tags, the client <em class="bcp14">SHOULD</em> generate an If-None-Match header field containing a list of those entity-tags when making a GET request; this allows recipient
    977981         servers to send a <a href="#status.304" class="smpl">304 (Not Modified)</a> response to indicate when one of those stored responses matches the selected representation.
    978982      </p>
    979       <p id="rfc.section.3.2.p.6">If-None-Match can also be used with a value of "*" to prevent an unsafe request method (e.g., PUT) from inadvertently modifying
     983      <p id="rfc.section.3.2.p.7">If-None-Match can also be used with a value of "*" to prevent an unsafe request method (e.g., PUT) from inadvertently modifying
    980984         an existing representation of the target resource when the client believes that the resource does not have a current representation
    981985         (<a href="p2-semantics.html#safe.methods" title="Safe Methods">Section 4.2.1</a> of <a href="#Part2" id="rfc.xref.Part2.5"><cite title="Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content">[Part2]</cite></a>). This is a variation on the "lost update" problem that might arise if more than one client attempts to create an initial
    982986         representation for the target resource.
    983987      </p>
    984       <p id="rfc.section.3.2.p.7">An origin server that receives an If-None-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server has a current representation for the target resource.
     988      <p id="rfc.section.3.2.p.8">An origin server that receives an If-None-Match header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). If the field-value is "*", the condition is false if the origin server has a current representation for the target resource.
    985989         If the field-value is a list of entity-tags, the condition is false if one of the listed tags match the entity-tag of the
    986990         selected representation.
    987991      </p>
    988       <p id="rfc.section.3.2.p.8">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if the condition evaluates to false; instead, the origin server <em class="bcp14">MUST</em> respond with either a) the <a href="#status.304" class="smpl">304 (Not Modified)</a> status code if the request method is GET or HEAD; or, b) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code for all other request methods.
     992      <p id="rfc.section.3.2.p.9">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if the condition evaluates to false; instead, the origin server <em class="bcp14">MUST</em> respond with either a) the <a href="#status.304" class="smpl">304 (Not Modified)</a> status code if the request method is GET or HEAD; or, b) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code for all other request methods.
    989993      </p>
    990994      <div id="rfc.iref.i.3"></div>
    991995      <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a>&nbsp;<a id="header.if-modified-since" href="#header.if-modified-since">If-Modified-Since</a></h2>
    992       <p id="rfc.section.3.3.p.1">The "If-Modified-Since" header field can be used with GET or HEAD to make the method conditional by modification date: if
    993          the selected representation has not been modified since the time specified in this field, then respond with a <a href="#status.304" class="smpl">304 (Not Modified)</a> status code and only send metadata that might be useful for identifying or updating a cached representation. Hence, transfer
     996      <p id="rfc.section.3.3.p.1">The "If-Modified-Since" header field makes the GET or HEAD request method conditional on the selected representation's modification
     997         date being more recent than the date provided in the field-value: if the selected representation has not been modified since
     998         the time specified in this field, then respond with a <a href="#status.304" class="smpl">304 (Not Modified)</a> status code and only send metadata that might be useful for identifying or updating a cached representation. Hence, transfer
    994999         of the selected representation's data is avoided if that data has not changed.
    9951000      </p>
     
    10171022      </p>
    10181023      <p id="rfc.section.3.3.p.10">When used for limiting the scope of retrieval to a recent time window, a user agent will generate an If-Modified-Since field
    1019          value based on either its own local clock or a <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field received from the server during a past run. Origin servers that choose an exact timestamp match based on the
     1024         value based on either its own local clock or a <a href="p2-semantics.html#header.date" class="smpl">Date</a> header field received from the server in a prior response. Origin servers that choose an exact timestamp match based on the
    10201025         selected representation's <a href="#header.last-modified" class="smpl">Last-Modified</a> field will not be able to help the user agent limit its data transfers to only those changed during the specified window.
    10211026      </p>
     
    10391044         (i.e., to prevent the "lost update" problem). It can also be used with safe methods to abort a request if the <a href="p2-semantics.html#representations" class="smpl">selected representation</a> does not match one already stored (or partially stored) from a prior request.
    10401045      </p>
    1041       <p id="rfc.section.3.4.p.9">An origin server that receives an If-Unmodified-Since header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). The condition is false if the selected representation has been modified since the time specified in this field.
     1046      <p id="rfc.section.3.4.p.9">An origin server that receives an If-Unmodified-Since header field <em class="bcp14">MUST</em> evaluate the condition prior to performing the method (<a href="#evaluation" title="Evaluation">Section&nbsp;5</a>). The condition is false if the selected representation's last modification date is more recent than the date provided in
     1047         the field-value.
    10421048      </p>
    10431049      <p id="rfc.section.3.4.p.10">An origin server <em class="bcp14">MUST NOT</em> perform the requested method if a received If-Unmodified-Since condition evaluates to false; instead the origin server <em class="bcp14">MUST</em> respond with either: a) the <a href="#status.412" class="smpl">412 (Precondition Failed)</a> status code; or, b) one of the <a href="p2-semantics.html#status.2xx" class="smpl">2xx (Successful)</a> status codes if the origin server has verified that a state change is being requested and the final state is already reflected
  • draft-ietf-httpbis/latest/p4-conditional.xml

    r2381 r2387  
    674674   entity-tag matching a member of the list of entity-tags provided in the
    675675   field-value.
     676</t>
     677<t>
    676678   A recipient &MUST; use the strong comparison function when comparing
    677679   entity-tags for If-Match (<xref target="entity.tag.comparison"/>).
     
    727729   The "If-None-Match" header field makes the request method conditional on
    728730   the recipient cache or origin server either not having a current
    729    representation for the target resource, when the field-value is "*", or
    730    not having a current representation that has an entity-tag matching a
    731    member of the list of entity-tags provided in the field-value.
     731   representation of the target resource, when the field-value is "*", or
     732   not having a current representation of the target resource that has an
     733   entity-tag matching a member of the list of entity-tags provided in the
     734   field-value.
     735</t>
     736<t>
    732737   A recipient &MUST; use the weak comparison function when comparing
    733738   entity-tags for If-None-Match (<xref target="entity.tag.comparison"/>).
     
    788793  <x:anchor-alias value="If-Modified-Since"/>
    789794<t>
    790    The "If-Modified-Since" header field can be used with GET or HEAD to make
    791    the method conditional by modification date: if the selected representation
     795   The "If-Modified-Since" header field makes the GET or HEAD request method
     796   conditional on the selected representation's modification date being more
     797   recent than the date provided in the field-value: if the selected representation
    792798   has not been modified since the time specified in this field, then respond
    793799   with a <x:ref>304 (Not Modified)</x:ref> status code and only send
     
    850856   user agent will generate an If-Modified-Since field value based on either
    851857   its own local clock or a <x:ref>Date</x:ref> header field received from the
    852    server during a past run. Origin servers that choose an exact timestamp
     858   server in a prior response. Origin servers that choose an exact timestamp
    853859   match based on the selected representation's <x:ref>Last-Modified</x:ref>
    854860   field will not be able to help the user agent limit its data transfers to
     
    905911   evaluate the condition prior to performing the method
    906912   (<xref target="evaluation"/>). The condition is false if the selected
    907    representation has been modified since the time specified in this field.
     913   representation's last modification date is more recent than the date
     914   provided in the field-value.
    908915</t>
    909916<t>
Note: See TracChangeset for help on using the changeset viewer.