Mar 31, 2011, 5:11:25 AM (9 years ago)

editorial: rewrite introduction to p4 conditionals and compress some
the references to ABNF in other parts so that they don't impede the
readability of this part. Add informative ref to WebDAV spec.

Addresses #228

1 edited


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

    r1243 r1251  
    216216<section title="Introduction" anchor="introduction">
    218    This document defines HTTP/1.1 response metadata for indicating potential
    219    changes to payload content, including modification time stamps and opaque
    220    entity-tags, and the HTTP conditional request mechanisms that allow
    221    preconditions to be placed on a request method.  Conditional GET requests
    222    allow for efficient cache updates.  Other conditional request methods are
    223    used to protect against overwriting or misunderstanding the state of a
    224    resource that has been changed unbeknownst to the requesting client.
     218   This document defines the HTTP/1.1 conditional request mechanisms,
     219   including both response metadata that can be used to indicate or
     220   observe changes to resource state and request header fields that
     221   specify preconditions to be checked before performing the action
     222   given by the request method.  Conditional GET requests are the most
     223   efficient mechanism for HTTP cache updates.  Conditionals can be
     224   applied to state-changing methods, such as PUT and DELETE, to prevent
     225   the "lost update" problem: one client accidentally overwriting
     226   the work of another client that has been acting in parallel.
     229   Conditional request preconditions are based on the state of the target
     230   resource as a whole (its current value set) or the state as observed
     231   in a previously obtained representation (one value in that set).
     232   A resource might have multiple current representations, each with its
     233   own observable state.  The conditional request mechanisms assume that
     234   the mapping of requests to corresponding representations will be
     235   consistent over time if the server intends to take advantage of
     236   conditionals.  Regardless, if the mapping is inconsistent and
     237   the server is unable to select the appropriate representation, then
     238   no harm will result when the precondition evaluates to false.
    226240<t><iref primary="true" item="selected representation"/>
    227    We use the term "<x:dfn>selected representation</x:dfn>" 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>
    236    This document is currently disorganized in order to minimize the changes
    237    between drafts and enable reviewers to see the smaller errata changes.
    238    A future draft will reorganize the sections to better reflect the content.
    239    In particular, the sections on resource metadata will be discussed first
    240    and then followed by each conditional request header field, concluding with a
    241    definition of precedence and the expectation of ordering strong validator
    242    checks before weak validator checks.  It is likely that more content from
    243    &caching; will migrate to this part, where appropriate.
    244    The current mess reflects how widely dispersed these topics and associated
    245    requirements had become in <xref target="RFC2616"/>.
     241   We use the term "<x:dfn>selected representation</x:dfn>" to refer to
     242   the current representation of the target resource that would have been
     243   selected in a successful response if the same request had used the method
     244   GET and had excluded all of the conditional request header fields.
     245   The conditional request preconditions are evaluated by comparing the
     246   values provided in the request header fields to the current metadata
     247   for the selected representation.
    271273  <x:anchor-alias value="VCHAR"/>
    272274  <x:anchor-alias value="WSP"/>
     275  <x:anchor-alias value="core.rules"/>
     276  <x:anchor-alias value="quoted-string"/>
     277  <x:anchor-alias value="OWS"/>
     278  <x:anchor-alias value="HTTP-date"/>
    274280  This specification uses the ABNF syntax defined in &notation; (which
    287293  and WSP (whitespace).
    290 <section title="Core Rules" anchor="core.rules">
    291   <x:anchor-alias value="quoted-string"/>
    292   <x:anchor-alias value="OWS"/>
    293 <t>
    294   The core rules below are defined in &basic-rules;:
     296  The ABNF rules below are defined in other parts:
    296298<figure><artwork type="abnf2616">
    297299  <x:ref>quoted-string</x:ref> = &lt;quoted-string, defined in &basic-rules;&gt;
    298300  <x:ref>OWS</x:ref>           = &lt;OWS, defined in &basic-rules;&gt;
    299 </artwork></figure>
    300 </section>
    302 <section title="ABNF Rules defined in other Parts of the Specification" anchor="abnf.dependencies">
    303   <x:anchor-alias value="HTTP-date"/>
    304 <t>
    305   The ABNF rules below are defined in other parts:
    306 </t>
    307 <figure><!--Part1--><artwork type="abnf2616">
    308301  <x:ref>HTTP-date</x:ref>     = &lt;HTTP-date, defined in &full-date;&gt;
    312 </section>
    314 </section>
    316 <section title="Entity-Tags" anchor="entity.tags">
     306<section title="Resource State Metadata" anchor="resource.metadata">
     308   This specification defines two forms of metadata that are commonly used
     309   to observe resource state and test for preconditions: modification dates
     310   and opaque entity tags.  Additional metadata that reflects resource state
     311   has been defined by various extensions of HTTP, such as WebDAV
     312   <xref target="RFC4918"/>, that are beyond the scope of this specification.
     315<section title="Entity Tags" anchor="entity.tags">
    317316  <x:anchor-alias value="entity-tag"/>
    318317  <x:anchor-alias value="opaque-tag"/>
    406405  </t>
     1447<reference anchor='RFC4918'>
     1448  <front>
     1449    <title>HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)</title>
     1450    <author initials="L.M." surname="Dusseault" fullname="Lisa Dusseault" role="editor" >
     1451      <organization abbrev="CommerceNet">CommerceNet</organization>
     1452      <address><email>ldusseault@commerce.net</email></address>
     1453    </author>
     1454    <date month="June" year="2007" />
     1455  </front>
     1456  <seriesInfo name='RFC' value='4918' />
Note: See TracChangeset for help on using the changeset viewer.