| draft-ietf-httpbis-p4-conditional-23.txt |  | draft-ietf-httpbis-p4-conditional-24.txt |
--- | --- | --- | --- | ---
| HTTPbis Working Group R. Fielding, Ed. |  | HTTPbis Working Group R. Fielding, Ed. |
| Internet-Draft Adobe |  | Internet-Draft Adobe |
| Obsoletes: 2616 (if approved) J. Reschke, Ed. |  | Obsoletes: 2616 (if approved) J. Reschke, Ed. |
| Intended status: Standards Track greenbytes |  | Intended status: Standards Track greenbytes |
| Expires: January 16, 2014 July 15, 2013 |  | Expires: March 29, 2014 September 25, 2013 |
| Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests |  | Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests |
| draft-ietf-httpbis-p4-conditional-23 |  | draft-ietf-httpbis-p4-conditional-24 |
| Abstract |  | Abstract |
| The Hypertext Transfer Protocol (HTTP) is an application-level |  | The Hypertext Transfer Protocol (HTTP) is an application-level |
| protocol for distributed, collaborative, hypertext information |  | protocol for distributed, collaborative, hypertext information |
| systems. This document defines HTTP/1.1 conditional requests, |  | systems. This document defines HTTP/1.1 conditional requests, |
| including metadata header fields for indicating state changes, |  | including metadata header fields for indicating state changes, |
| request header fields for making preconditions on such state, and |  | request header fields for making preconditions on such state, and |
| rules for constructing the responses to a conditional request when |  | rules for constructing the responses to a conditional request when |
| one or more preconditions evaluate to false. |  | one or more preconditions evaluate to false. |
| skipping to change at page 1, line 33 |  | skipping to change at page 1, line 33 |
| Discussion of this draft takes place on the HTTPBIS working group |  | Discussion of this draft takes place on the HTTPBIS working group |
| mailing list (ietf-http-wg@w3.org), which is archived at |  | mailing list (ietf-http-wg@w3.org), which is archived at |
| <http://lists.w3.org/Archives/Public/ietf-http-wg/>. |  | <http://lists.w3.org/Archives/Public/ietf-http-wg/>. |
| The current issues list is at |  | The current issues list is at |
| <http://tools.ietf.org/wg/httpbis/trac/report/3> and related |  | <http://tools.ietf.org/wg/httpbis/trac/report/3> and related |
| documents (including fancy diffs) can be found at |  | documents (including fancy diffs) can be found at |
| <http://tools.ietf.org/wg/httpbis/>. |  | <http://tools.ietf.org/wg/httpbis/>. |
| The changes in this draft are summarized in Appendix D.4. |  | The changes in this draft are summarized in Appendix D.5. |
| Status of This Memo |  | Status of This Memo |
| This Internet-Draft is submitted in full conformance with the |  | This Internet-Draft is submitted in full conformance with the |
| provisions of BCP 78 and BCP 79. |  | provisions of BCP 78 and BCP 79. |
| Internet-Drafts are working documents of the Internet Engineering |  | Internet-Drafts are working documents of the Internet Engineering |
| Task Force (IETF). Note that other groups may also distribute |  | Task Force (IETF). Note that other groups may also distribute |
| working documents as Internet-Drafts. The list of current Internet- |  | working documents as Internet-Drafts. The list of current Internet- |
| Drafts is at http://datatracker.ietf.org/drafts/current/. |  | Drafts is at http://datatracker.ietf.org/drafts/current/. |
| Internet-Drafts are draft documents valid for a maximum of six months |  | Internet-Drafts are draft documents valid for a maximum of six months |
| and may be updated, replaced, or obsoleted by other documents at any |  | and may be updated, replaced, or obsoleted by other documents at any |
| time. It is inappropriate to use Internet-Drafts as reference |  | time. It is inappropriate to use Internet-Drafts as reference |
| material or to cite them other than as "work in progress." |  | material or to cite them other than as "work in progress." |
| This Internet-Draft will expire on January 16, 2014. |  | This Internet-Draft will expire on March 29, 2014. |
| Copyright Notice |  | Copyright Notice |
| Copyright (c) 2013 IETF Trust and the persons identified as the |  | Copyright (c) 2013 IETF Trust and the persons identified as the |
| document authors. All rights reserved. |  | document authors. All rights reserved. |
| This document is subject to BCP 78 and the IETF Trust's Legal |  | This document is subject to BCP 78 and the IETF Trust's Legal |
| Provisions Relating to IETF Documents |  | Provisions Relating to IETF Documents |
| (http://trustee.ietf.org/license-info) in effect on the date of |  | (http://trustee.ietf.org/license-info) in effect on the date of |
| publication of this document. Please review these documents |  | publication of this document. Please review these documents |
| skipping to change at page 3, line 26 |  | skipping to change at page 3, line 26 |
| 2.3.1. Generation . . . . . . . . . . . . . . . . . . . . . . 10 |  | 2.3.1. Generation . . . . . . . . . . . . . . . . . . . . . . 10 |
| 2.3.2. Comparison . . . . . . . . . . . . . . . . . . . . . . 10 |  | 2.3.2. Comparison . . . . . . . . . . . . . . . . . . . . . . 10 |
| 2.3.3. Example: Entity-tags Varying on Content-Negotiated |  | 2.3.3. Example: Entity-tags Varying on Content-Negotiated |
| Resources . . . . . . . . . . . . . . . . . . . . . . 11 |  | Resources . . . . . . . . . . . . . . . . . . . . . . 11 |
| 2.4. When to Use Entity-tags and Last-Modified Dates . . . . . 12 |  | 2.4. When to Use Entity-tags and Last-Modified Dates . . . . . 12 |
| 3. Precondition Header Fields . . . . . . . . . . . . . . . . . . 13 |  | 3. Precondition Header Fields . . . . . . . . . . . . . . . . . . 13 |
| 3.1. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 13 |  | 3.1. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 13 |
| 3.2. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 14 |  | 3.2. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 14 |
| 3.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 15 |  | 3.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 15 |
| 3.4. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 16 |  | 3.4. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 16 |
| 3.5. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 16 |  | 3.5. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 18 |
| 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 17 |  | 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 18 |
| 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 17 |  | 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 18 |
| 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 17 |  | 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 18 |
| 5. Evaluation and Precedence . . . . . . . . . . . . . . . . . . 17 |  | 5. Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 19 |
| 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 |  | 6. Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . 19 |
| 6.1. Status Code Registration . . . . . . . . . . . . . . . . . 20 |  | 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 |
| 6.2. Header Field Registration . . . . . . . . . . . . . . . . 20 |  | 7.1. Status Code Registration . . . . . . . . . . . . . . . . . 21 |
| 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 |  | 7.2. Header Field Registration . . . . . . . . . . . . . . . . 21 |
| 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 |  | 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 |
| 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 |  | 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 |
| 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 |  | 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 |
| 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 |  | 10.1. Normative References . . . . . . . . . . . . . . . . . . . 23 |
| Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 22 |  | 10.2. Informative References . . . . . . . . . . . . . . . . . . 23 |
| Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 22 |  | Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 23 |
| Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 23 |  | Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 24 |
|  |  | Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 24 |
| Appendix D. Change Log (to be removed by RFC Editor before |  | Appendix D. Change Log (to be removed by RFC Editor before |
| publication) . . . . . . . . . . . . . . . . . . . . 23 |  | publication) . . . . . . . . . . . . . . . . . . . . 25 |
| D.1. Since draft-ietf-httpbis-p4-conditional-19 . . . . . . . . 23 |  | D.1. Since draft-ietf-httpbis-p4-conditional-19 . . . . . . . . 25 |
| D.2. Since draft-ietf-httpbis-p4-conditional-20 . . . . . . . . 24 |  | D.2. Since draft-ietf-httpbis-p4-conditional-20 . . . . . . . . 26 |
| D.3. Since draft-ietf-httpbis-p4-conditional-21 . . . . . . . . 24 |  | D.3. Since draft-ietf-httpbis-p4-conditional-21 . . . . . . . . 26 |
| D.4. Since draft-ietf-httpbis-p4-conditional-22 . . . . . . . . 25 |  | D.4. Since draft-ietf-httpbis-p4-conditional-22 . . . . . . . . 26 |
| Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 |  | D.5. Since draft-ietf-httpbis-p4-conditional-23 . . . . . . . . 27 |
|  |  | Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 |
| 1. Introduction |  | 1. Introduction |
| Conditional requests are HTTP requests [Part2] that include one or |  | Conditional requests are HTTP requests [Part2] that include one or |
| more header fields indicating a precondition to be tested before |  | more header fields indicating a precondition to be tested before |
| applying the method semantics to the target resource. This document |  | applying the method semantics to the target resource. This document |
| defines the HTTP/1.1 conditional request mechanisms in terms of the |  | defines the HTTP/1.1 conditional request mechanisms in terms of the |
| architecture, syntax notation, and conformance criteria defined in |  | architecture, syntax notation, and conformance criteria defined in |
| [Part1]. |  | [Part1]. |
| skipping to change at page 4, line 33 |  | skipping to change at page 4, line 33 |
| set). A resource might have multiple current representations, each |  | set). A resource might have multiple current representations, each |
| with its own observable state. The conditional request mechanisms |  | with its own observable state. The conditional request mechanisms |
| assume that the mapping of requests to a "selected representation" |  | assume that the mapping of requests to a "selected representation" |
| (Section 3 of [Part2]) will be consistent over time if the server |  | (Section 3 of [Part2]) will be consistent over time if the server |
| intends to take advantage of conditionals. Regardless, if the |  | intends to take advantage of conditionals. Regardless, if the |
| mapping is inconsistent and the server is unable to select the |  | mapping is inconsistent and the server is unable to select the |
| appropriate representation, then no harm will result when the |  | appropriate representation, then no harm will result when the |
| precondition evaluates to false. |  | precondition evaluates to false. |
| The conditional request preconditions defined by this specification |  | The conditional request preconditions defined by this specification |
| are evaluated by comparing the validators provided in the conditional |  | (Section 3) are evaluated when applicable to the recipient |
| request header fields to the current validators for the selected |  | (Section 5) according to their order of precedence (Section 6). |
| representation in the order defined by Section 5. |  |  |
| 1.1. Conformance and Error Handling |  | 1.1. Conformance and Error Handling |
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |  | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |  | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| document are to be interpreted as described in [RFC2119]. |  | document are to be interpreted as described in [RFC2119]. |
| Conformance criteria and considerations regarding error handling are |  | Conformance criteria and considerations regarding error handling are |
| defined in Section 2.5 of [Part1]. |  | defined in Section 2.5 of [Part1]. |
| 1.2. Syntax Notation |  | 1.2. Syntax Notation |
| This specification uses the Augmented Backus-Naur Form (ABNF) |  | This specification uses the Augmented Backus-Naur Form (ABNF) |
| notation of [RFC5234] with the list rule extension defined in Section |  | notation of [RFC5234] with the list rule extension defined in Section |
| 1.2 of [Part1]. Appendix B describes rules imported from other |  | 7 of [Part1]. Appendix B describes rules imported from other |
| documents. Appendix C shows the collected ABNF with the list rule |  | documents. Appendix C shows the collected ABNF with the list rule |
| expanded. |  | expanded. |
| 2. Validators |  | 2. Validators |
| This specification defines two forms of metadata that are commonly |  | This specification defines two forms of metadata that are commonly |
| used to observe resource state and test for preconditions: |  | used to observe resource state and test for preconditions: |
| modification dates (Section 2.2) and opaque entity tags |  | modification dates (Section 2.2) and opaque entity tags |
| (Section 2.3). Additional metadata that reflects resource state has |  | (Section 2.3). Additional metadata that reflects resource state has |
| been defined by various extensions of HTTP, such as WebDAV [RFC4918], |  | been defined by various extensions of HTTP, such as WebDAV [RFC4918], |
| skipping to change at page 6, line 12 |  | skipping to change at page 6, line 12 |
| are based on strict revision control, wherein each change to a |  | are based on strict revision control, wherein each change to a |
| representation always results in a unique node name and revision |  | representation always results in a unique node name and revision |
| identifier being assigned before the representation is made |  | identifier being assigned before the representation is made |
| accessible to GET. A collision-resistant hash function applied to |  | accessible to GET. A collision-resistant hash function applied to |
| the representation data is also sufficient if the data is available |  | the representation data is also sufficient if the data is available |
| prior to the response header fields being sent and the digest does |  | prior to the response header fields being sent and the digest does |
| not need to be recalculated every time a validation request is |  | not need to be recalculated every time a validation request is |
| received. However, if a resource has distinct representations that |  | received. However, if a resource has distinct representations that |
| differ only in their metadata, such as might occur with content |  | differ only in their metadata, such as might occur with content |
| negotiation over media types that happen to share the same data |  | negotiation over media types that happen to share the same data |
| format, then the origin server SHOULD incorporate additional |  | format, then the origin server needs to incorporate additional |
| information in the validator to distinguish those representations. |  | information in the validator to distinguish those representations. |
| In contrast, a "weak validator" is representation metadata that might |  | In contrast, a "weak validator" is representation metadata that might |
| not change for every change to the representation data. This |  | not change for every change to the representation data. This |
| weakness might be due to limitations in how the value is calculated, |  | weakness might be due to limitations in how the value is calculated, |
| such as clock resolution or an inability to ensure uniqueness for all |  | such as clock resolution or an inability to ensure uniqueness for all |
| possible representations of the resource, or due to a desire by the |  | possible representations of the resource, or due to a desire by the |
| resource owner to group representations by some self-determined set |  | resource owner to group representations by some self-determined set |
| of equivalency rather than unique sequences of data. An origin |  | of equivalency rather than unique sequences of data. An origin |
| server SHOULD change a weak entity-tag whenever it considers prior |  | server SHOULD change a weak entity-tag whenever it considers prior |
| skipping to change at page 6, line 48 |  | skipping to change at page 6, line 48 |
| Likewise, a validator is weak if it is shared by two or more |  | Likewise, a validator is weak if it is shared by two or more |
| representations of a given resource at the same time, unless those |  | representations of a given resource at the same time, unless those |
| representations have identical representation data. For example, if |  | representations have identical representation data. For example, if |
| the origin server sends the same validator for a representation with |  | the origin server sends the same validator for a representation with |
| a gzip content coding applied as it does for a representation with no |  | a gzip content coding applied as it does for a representation with no |
| content coding, then that validator is weak. However, two |  | content coding, then that validator is weak. However, two |
| simultaneous representations might share the same strong validator if |  | simultaneous representations might share the same strong validator if |
| they differ only in the representation metadata, such as when two |  | they differ only in the representation metadata, such as when two |
| different media types are available for the same representation data. |  | different media types are available for the same representation data. |
| A "use" of a validator occurs when either a client generates a |  | Strong validators are usable for all conditional requests, including |
| request and includes the validator in a precondition or when a server |  | cache validation, partial content ranges, and "lost update" |
| compares two validators. Weak validators are only usable in contexts |  | avoidance. Weak validators are only usable when the client does not |
| that do not depend on exact equality of the representation data. |  | require exact equality with previously obtained representation data, |
|  |  | such as when validating a cache entry or limiting a web traversal to |
| Strong validators are usable and preferred for all conditional |  | recent changes. |
| requests, including cache validation, partial content ranges, and |  |  |
| "lost update" avoidance. |  |  |
| 2.2. Last-Modified |  | 2.2. Last-Modified |
| The "Last-Modified" header field in a response provides a timestamp |  | The "Last-Modified" header field in a response provides a timestamp |
| indicating the date and time at which the origin server believes the |  | indicating the date and time at which the origin server believes the |
| selected representation was last modified, as determined at the |  | selected representation was last modified, as determined at the |
| conclusion of handling the request. |  | conclusion of handling the request. |
| Last-Modified = HTTP-date |  | Last-Modified = HTTP-date |
| An example of its use is |  | An example of its use is |
| Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT |  | Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT |
| 2.2.1. Generation |  | 2.2.1. Generation |
| Origin servers SHOULD send Last-Modified for any selected |  | An origin server SHOULD send Last-Modified for any selected |
| representation for which a last modification date can be reasonably |  | representation for which a last modification date can be reasonably |
| and consistently determined, since its use in conditional requests |  | and consistently determined, since its use in conditional requests |
| and evaluating cache freshness ([Part6]) results in a substantial |  | and evaluating cache freshness ([Part6]) results in a substantial |
| reduction of HTTP traffic on the Internet and can be a significant |  | reduction of HTTP traffic on the Internet and can be a significant |
| factor in improving service scalability and reliability. |  | factor in improving service scalability and reliability. |
| A representation is typically the sum of many parts behind the |  | A representation is typically the sum of many parts behind the |
| resource interface. The last-modified time would usually be the most |  | resource interface. The last-modified time would usually be the most |
| recent time that any of those parts were changed. How that value is |  | recent time that any of those parts were changed. How that value is |
| determined for any given resource is an implementation detail beyond |  | determined for any given resource is an implementation detail beyond |
| skipping to change at page 10, line 23 |  | skipping to change at page 10, line 23 |
| For example, a resource that has implementation-specific versioning |  | For example, a resource that has implementation-specific versioning |
| applied to all changes might use an internal revision number, perhaps |  | applied to all changes might use an internal revision number, perhaps |
| combined with a variance identifier for content negotiation, to |  | combined with a variance identifier for content negotiation, to |
| accurately differentiate between representations. Other |  | accurately differentiate between representations. Other |
| implementations might use a collision-resistant hash of |  | implementations might use a collision-resistant hash of |
| representation content, a combination of various filesystem |  | representation content, a combination of various filesystem |
| attributes, or a modification timestamp that has sub-second |  | attributes, or a modification timestamp that has sub-second |
| resolution. |  | resolution. |
| Origin servers SHOULD send ETag for any selected representation for |  | An origin server SHOULD send ETag for any selected representation for |
| which detection of changes can be reasonably and consistently |  | which detection of changes can be reasonably and consistently |
| determined, since the entity-tag's use in conditional requests and |  | determined, since the entity-tag's use in conditional requests and |
| evaluating cache freshness ([Part6]) can result in a substantial |  | evaluating cache freshness ([Part6]) can result in a substantial |
| reduction of HTTP network traffic and can be a significant factor in |  | reduction of HTTP network traffic and can be a significant factor in |
| improving service scalability and reliability. |  | improving service scalability and reliability. |
| 2.3.2. Comparison |  | 2.3.2. Comparison |
| There are two entity-tag comparison functions, depending on whether |  | There are two entity-tag comparison functions, depending on whether |
| the comparison context allows the use of weak validators or not: |  | the comparison context allows the use of weak validators or not: |
| skipping to change at page 12, line 35 |  | skipping to change at page 12, line 35 |
| if it is unfeasible to send a strong entity-tag. |  | if it is unfeasible to send a strong entity-tag. |
| o SHOULD send a Last-Modified value if it is feasible to send one. |  | o SHOULD send a Last-Modified value if it is feasible to send one. |
| In other words, the preferred behavior for an origin server is to |  | In other words, the preferred behavior for an origin server is to |
| send both a strong entity-tag and a Last-Modified value in successful |  | send both a strong entity-tag and a Last-Modified value in successful |
| responses to a retrieval request. |  | responses to a retrieval request. |
| A client: |  | A client: |
| o MUST use that entity-tag in any cache-conditional request (using |  | o MUST send that entity-tag in any cache validation request (using |
| If-Match or If-None-Match) if an entity-tag has been provided by |  | If-Match or If-None-Match) if an entity-tag has been provided by |
| the origin server. |  | the origin server. |
| o SHOULD use the Last-Modified value in non-subrange cache- |  | o SHOULD send the Last-Modified value in non-subrange cache |
| conditional requests (using If-Modified-Since) if only a Last- |  | validation requests (using If-Modified-Since) if only a Last- |
| Modified value has been provided by the origin server. |  | Modified value has been provided by the origin server. |
| o MAY use the Last-Modified value in subrange cache-conditional |  | o MAY send the Last-Modified value in subrange cache validation |
| requests (using If-Unmodified-Since) if only a Last-Modified value |  | requests (using If-Unmodified-Since) if only a Last-Modified value |
| has been provided by an HTTP/1.0 origin server. The user agent |  | has been provided by an HTTP/1.0 origin server. The user agent |
| SHOULD provide a way to disable this, in case of difficulty. |  | SHOULD provide a way to disable this, in case of difficulty. |
| o SHOULD use both validators in cache-conditional requests if both |  | o SHOULD send both validators in cache validation requests if both |
| an entity-tag and a Last-Modified value have been provided by the |  | an entity-tag and a Last-Modified value have been provided by the |
| origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to |  | origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to |
| respond appropriately. |  | respond appropriately. |
| 3. Precondition Header Fields |  | 3. Precondition Header Fields |
| This section defines the syntax and semantics of HTTP/1.1 header |  | This section defines the syntax and semantics of HTTP/1.1 header |
| fields for applying preconditions on requests. Section 5 defines |  | fields for applying preconditions on requests. Section 5 defines |
| when the preconditions are applied and the order of evaluation when |  | when the preconditions are applied. Section 6 defines the order of |
| more than one precondition is present. |  | evaluation when more than one precondition is present. |
| 3.1. If-Match |  | 3.1. If-Match |
| The "If-Match" header field can be used to make a request method |  | The "If-Match" header field makes the request method conditional on |
| conditional on the current existence or value of an entity-tag for |  | the recipient origin server either having at least one current |
| one or more representations of the target resource. |  | representation of the target resource, when the field-value is "*", |
|  |  | or having a current representation of the target resource that has an |
|  |  | entity-tag matching a member of the list of entity-tags provided in |
|  |  | the field-value. |
| If-Match is generally useful for resource update requests, such as |  | An origin server MUST use the strong comparison function when |
| PUT requests, as a means for protecting against accidental overwrites |  | comparing entity-tags for If-Match (Section 2.3.2), since the client |
| when multiple clients are acting in parallel on the same resource |  | intends this precondition to prevent the method from being applied if |
| (i.e., the "lost update" problem). An If-Match field-value of "*" |  | there have been any changes to the representation data. |
| places the precondition on the existence of any current |  |  |
| representation for the target resource. |  |  |
| If-Match = "*" / 1#entity-tag |  | If-Match = "*" / 1#entity-tag |
| The If-Match condition is met if and only if any of the entity-tags |  |  |
| listed in the If-Match field value match the entity-tag of the |  |  |
| selected representation using the weak comparison function (as per |  |  |
| Section 2.3.2), or if "*" is given and any current representation |  |  |
| exists for the target resource. |  |  |
| If the condition is met, the server MAY perform the request method. |  |  |
| Origin servers MUST NOT perform the requested method if the condition |  |  |
| is not met; instead they MUST respond with the 412 (Precondition |  |  |
| Failed) status code. |  |  |
| Proxy servers using a cached response as the selected representation |  |  |
| MUST NOT perform the requested method if the condition is not met; |  |  |
| instead, they MUST forward the request towards the origin server. |  |  |
| Examples: |  | Examples: |
| If-Match: "xyzzy" |  | If-Match: "xyzzy" |
| If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |  | If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |
| If-Match: * |  | If-Match: * |
|  |  | If-Match is most often used with state-changing methods (e.g., POST, |
|  |  | PUT, DELETE) to prevent accidental overwrites when multiple user |
|  |  | agents might be acting in parallel on the same resource (i.e., to |
|  |  | prevent the "lost update" problem). It can also be used with safe |
|  |  | methods to abort a request if the selected representation does not |
|  |  | match one already stored (or partially stored) from a prior request. |
|  |  | An origin server that receives an If-Match header field MUST evaluate |
|  |  | the condition prior to performing the method (Section 5). If the |
|  |  | field-value is "*", the condition is false if the origin server does |
|  |  | not have a current representation for the target 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 of the selected |
|  |  | representation. |
|  |  | An origin server MUST NOT perform the requested method if a received |
|  |  | If-Match condition evaluates to false; instead the origin server MUST |
|  |  | respond with either: a) the 412 (Precondition Failed) status code; |
|  |  | or, b) one of the 2xx (Successful) status codes if the origin server |
|  |  | has verified that a state change is being requested and the final |
|  |  | state is already reflected in the current state of the target |
|  |  | resource (i.e., the change requested by the user agent has already |
|  |  | succeeded, but the user agent might not be aware of it, perhaps |
|  |  | because the prior response was lost or a compatible change was made |
|  |  | by some other user agent). In the latter case, the origin server |
|  |  | MUST NOT send a validator header field in the response unless it can |
|  |  | verify that the request is a duplicate of an immediately prior change |
|  |  | made by the same user agent. |
|  |  | The If-Match header field can be ignored by caches and intermediaries |
|  |  | because it is not applicable to a stored response. |
| 3.2. If-None-Match |  | 3.2. If-None-Match |
| The "If-None-Match" header field can be used to make a request method |  | The "If-None-Match" header field makes the request method conditional |
| conditional on not matching any of the current entity-tag values for |  | on a recipient cache or origin server either not having any current |
| representations of the target resource. |  | representation of the target resource, when the field-value is "*", |
|  |  | or having a selected representation with an entity-tag that does not |
|  |  | match any of those listed in the field-value. |
|  |  | A recipient MUST use the weak comparison function when comparing |
|  |  | entity-tags for If-None-Match (Section 2.3.2), since weak entity-tags |
|  |  | can be used for cache validation even if there have been changes to |
|  |  | the representation data. |
|  |  | If-None-Match = "*" / 1#entity-tag |
|  |  | Examples: |
|  |  | If-None-Match: "xyzzy" |
|  |  | If-None-Match: W/"xyzzy" |
|  |  | If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |
|  |  | If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" |
|  |  | If-None-Match: * |
| If-None-Match is primarily used in conditional GET requests to enable |  | If-None-Match is primarily used in conditional GET requests to enable |
| efficient updates of cached information with a minimum amount of |  | efficient updates of cached information with a minimum amount of |
| transaction overhead. A client that has one or more representations |  | transaction overhead. When a client desires to update one or more |
| previously obtained from the target resource can send If-None-Match |  | stored responses that have entity-tags, the client SHOULD generate an |
| with a list of the associated entity-tags in the hope of receiving a |  | If-None-Match header field containing a list of those entity-tags |
| 304 (Not Modified) response if at least one of those representations |  | when making a GET request; this allows recipient servers to send a |
| matches the selected representation. |  | 304 (Not Modified) response to indicate when one of those stored |
|  |  | responses matches the selected representation. |
| If-None-Match can also be used with a value of "*" to prevent an |  | If-None-Match can also be used with a value of "*" to prevent an |
| unsafe request method (e.g., PUT) from inadvertently modifying an |  | unsafe request method (e.g., PUT) from inadvertently modifying an |
| existing representation of the target resource when the client |  | existing representation of the target resource when the client |
| believes that the resource does not have a current representation |  | believes that the resource does not have a current representation |
| (Section 4.2.1 of [Part2]). This is a variation on the "lost update" |  | (Section 4.2.1 of [Part2]). This is a variation on the "lost update" |
| problem that might arise if more than one client attempts to create |  | problem that might arise if more than one client attempts to create |
| an initial representation for the target resource. |  | an initial representation for the target resource. |
| If-None-Match = "*" / 1#entity-tag |  | An origin server that receives an If-None-Match header field MUST |
|  |  | evaluate the condition prior to performing the method (Section 5). |
| The If-None-Match condition is met if and only if none of the entity- |  | If the field-value is "*", the condition is false if the origin |
| tags listed in the If-None-Match field value match the entity-tag of |  | server has a current representation for the target resource. If the |
| the selected representation using the weak comparison function (as |  | field-value is a list of entity-tags, the condition is false if one |
| per Section 2.3.2), or if "*" is given and no current representation |  | of the listed tags match the entity-tag of the selected |
| exists for that resource. |  | representation. |
| If the condition is not met, the server MUST NOT perform the |  |  |
| requested method. Instead, if the request method was GET or HEAD, |  |  |
| the server SHOULD respond with a 304 (Not Modified) status code, |  |  |
| including the cache-related header fields (particularly ETag) of the |  |  |
| selected representation that has a matching entity-tag. For all |  |  |
| other request methods, the server MUST respond with a 412 |  |  |
| (Precondition Failed) status code when the condition is not met. |  |  |
| If the condition is met, the server MAY perform the requested method |  |  |
| and MUST ignore any If-Modified-Since header field(s) in the request. |  |  |
| That is, if no entity-tags match, then the server MUST NOT send a 304 |  |  |
| (Not Modified) response. |  |  |
| Examples: |  | An origin server MUST NOT perform the requested method if the |
|  |  | condition evaluates to false; instead, the origin server MUST respond |
|  |  | with either a) the 304 (Not Modified) status code if the request |
|  |  | method is GET or HEAD; or, b) the 412 (Precondition Failed) status |
|  |  | code for all other request methods. |
| If-None-Match: "xyzzy" |  | Requirements on cache handling of a received If-None-Match header |
| If-None-Match: W/"xyzzy" |  | field are defined in Section 4.3.2 of [Part6]. |
| If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |  |  |
| If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" |  |  |
| If-None-Match: * |  |  |
| 3.3. If-Modified-Since |  | 3.3. If-Modified-Since |
| The "If-Modified-Since" header field can be used with GET or HEAD to |  | The "If-Modified-Since" header field makes a GET or HEAD request |
| make the method conditional by modification date: if the selected |  | method conditional on the selected representation's modification date |
| representation has not been modified since the time specified in this |  | being more recent than the date provided in the field-value. |
| field, then do not perform the request method; instead, respond as |  | Transfer of the selected representation's data is avoided if that |
| detailed below. |  | data has not changed. |
| If-Modified-Since = HTTP-date |  | If-Modified-Since = HTTP-date |
| An example of the field is: |  | An example of the field is: |
| If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT |  | If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
| A GET method with an If-Modified-Since header field and no Range |  | A recipient MUST ignore If-Modified-Since if the request contains an |
| header field requests that the selected representation be transferred |  | If-None-Match header field; the condition in If-None-Match is |
| only if it has been modified since the date given by the If-Modified- |  | considered to be a more accurate replacement for the condition in If- |
| Since header field. The algorithm for determining this includes the |  | Modified-Since and the two are only combined for the sake of |
| following cases: |  | interoperating with older intermediaries that might not implement If- |
|  |  | None-Match. |
| 1. If the request would normally result in anything other than a 200 |  |  |
| (OK) status code, or if the passed If-Modified-Since date is |  |  |
| invalid, the response is exactly the same as for a normal GET. A |  |  |
| date that is later than the server's current time is invalid. |  |  |
| 2. If the selected representation has been modified since the If- |  | A recipient MUST ignore the If-Modified-Since header field if the |
| Modified-Since date, the response is exactly the same as for a |  | received field-value is not a valid HTTP-date, or if the request |
| normal GET. |  | method is neither GET nor HEAD. |
| 3. If the selected representation has not been modified since a |  | A recipient MUST interpret an If-Modified-Since field-value's |
| valid If-Modified-Since date, the server SHOULD send a 304 (Not |  | timestamp in terms of the origin server's clock. |
| Modified) response. |  |  |
| The two purposes of this feature are to allow efficient updates of |  | If-Modified-Since is typically used for two distinct purposes: 1) to |
| cached information, with a minimum amount of transaction overhead, |  | allow efficient updates of a cached representation that does not have |
| and to limit the scope of a web traversal to resources that have |  | an entity-tag; and, 2) to limit the scope of a web traversal to |
| recently changed. |  | resources that have recently changed. |
| When used for cache updates, a cache will typically use the value of |  | When used for cache updates, a cache will typically use the value of |
| the cached message's Last-Modified field to generate the field value |  | the cached message's Last-Modified field to generate the field value |
| of If-Modified-Since. This behavior is most interoperable for cases |  | of If-Modified-Since. This behavior is most interoperable for cases |
| where clocks are poorly synchronized or when the server has chosen to |  | where clocks are poorly synchronized or when the server has chosen to |
| only honor exact timestamp matches (due to a problem with Last- |  | only honor exact timestamp matches (due to a problem with Last- |
| Modified dates that appear to go "back in time" when the origin |  | Modified dates that appear to go "back in time" when the origin |
| server's clock is corrected or a representation is restored from an |  | server's clock is corrected or a representation is restored from an |
| archived backup). However, caches occasionally generate the field |  | archived backup). However, caches occasionally generate the field |
| value based on other data, such as the Date header field of the |  | value based on other data, such as the Date header field of the |
| cached message or the local clock time that the message was received, |  | cached message or the local clock time that the message was received, |
| particularly when the cached message does not contain a Last-Modified |  | particularly when the cached message does not contain a Last-Modified |
| field. |  | field. |
| When used for limiting the scope of retrieval to a recent time |  | When used for limiting the scope of retrieval to a recent time |
| window, a user agent will generate an If-Modified-Since field value |  | window, a user agent will generate an If-Modified-Since field value |
| based on either its own local clock or a Date header field received |  | based on either its own local clock or a Date header field received |
| from the server during a past run. Origin servers that choose an |  | from the server in a prior response. Origin servers that choose an |
| exact timestamp match based on the selected representation's Last- |  | exact timestamp match based on the selected representation's Last- |
| Modified field will not be able to help the user agent limit its data |  | Modified field will not be able to help the user agent limit its data |
| transfers to only those changed during the specified window. |  | transfers to only those changed during the specified window. |
| Note: If a client uses an arbitrary date in the If-Modified-Since |  | An origin server that receives an If-Modified-Since header field |
| header field instead of a date taken from a Last-Modified or Date |  | SHOULD evaluate the condition prior to performing the method |
| header field from the origin server, the client ought to be aware |  | (Section 5). The origin server SHOULD NOT perform the requested |
| that its date will be interpreted according to the server's |  | method if the selected representation's last modification date is |
| understanding of time. |  | earlier than or equal to the date provided in the field-value; |
|  |  | instead, the origin server SHOULD generate a 304 (Not Modified) |
|  |  | response, including only those metadata that are useful for |
|  |  | identifying or updating a previously cached response. |
|  |  | Requirements on cache handling of a received If-Modified-Since header |
|  |  | field are defined in Section 4.3.2 of [Part6]. |
| 3.4. If-Unmodified-Since |  | 3.4. If-Unmodified-Since |
| The "If-Unmodified-Since" header field can be used to make a request |  | The "If-Unmodified-Since" header field makes the request method |
| method conditional by modification date: if the selected |  | conditional on the selected representation's last modification date |
| representation has been modified since the time specified in this |  | being earlier than or equal to the date provided in the field-value. |
| field, then the server MUST NOT perform the requested operation and |  | This field accomplishes the same purpose as If-Match for cases where |
| MUST instead respond with the 412 (Precondition Failed) status code. |  | the user agent does not have an entity-tag for the representation. |
| If the selected representation has not been modified since the time |  |  |
| specified in this field, the server MAY perform the request. |  |  |
| If-Unmodified-Since = HTTP-date |  | If-Unmodified-Since = HTTP-date |
| An example of the field is: |  | An example of the field is: |
| If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT |  | If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
| A server MUST ignore the If-Unmodified-Since header field if the |  | A recipient MUST ignore If-Unmodified-Since if the request contains |
| received value is not a valid HTTP-date. |  | an If-Match header field; the condition in If-Match is considered to |
|  |  | be a more accurate replacement for the condition in If-Unmodified- |
|  |  | Since and the two are only combined for the sake of interoperating |
|  |  | with older intermediaries that might not implement If-Match. |
|  |  | A recipient MUST ignore the If-Unmodified-Since header field if the |
|  |  | received field-value is not a valid HTTP-date. |
|  |  | A recipient MUST interpret an If-Unmodified-Since field-value's |
|  |  | timestamp in terms of the origin server's clock. |
|  |  | If-Unmodified-Since is most often used with state-changing methods |
|  |  | (e.g., POST, PUT, DELETE) to prevent accidental overwrites when |
|  |  | multiple user agents might be acting in parallel on a resource that |
|  |  | does not supply entity-tags with its representations (i.e., to |
|  |  | prevent the "lost update" problem). It can also be used with safe |
|  |  | methods to abort a request if the selected representation does not |
|  |  | match one already stored (or partially stored) from a prior request. |
|  |  | An origin server that receives an If-Unmodified-Since header field |
|  |  | MUST evaluate the condition prior to performing the method |
|  |  | (Section 5). The origin server MUST NOT perform the requested method |
|  |  | if the selected representation's last modification date is more |
|  |  | recent than the date provided in the field-value; instead the origin |
|  |  | server MUST respond with either: a) the 412 (Precondition Failed) |
|  |  | status code; or, b) one of the 2xx (Successful) status codes if the |
|  |  | origin server has verified that a state change is being requested and |
|  |  | the final state is already reflected in the current state of the |
|  |  | target resource (i.e., the change requested by the user agent has |
|  |  | already succeeded, but the user agent might not be aware of that |
|  |  | because the prior response message was lost or a compatible change |
|  |  | was made by some other user agent). In the latter case, the origin |
|  |  | server MUST NOT send a validator header field in the response unless |
|  |  | it can verify that the request is a duplicate of an immediately prior |
|  |  | change made by the same user agent. |
|  |  | The If-Unmodified-Since header field can be ignored by caches and |
|  |  | intermediaries because it is not applicable to a stored response. |
| 3.5. If-Range |  | 3.5. If-Range |
| The "If-Range" header field provides a special conditional request |  | The "If-Range" header field provides a special conditional request |
| mechanism that is similar to If-Match and If-Unmodified-Since but |  | mechanism that is similar to the If-Match and If-Unmodified-Since |
| specific to range requests. If-Range is defined in Section 3.2 of |  | header fields but instructs the recipient to ignore the Range header |
| [Part5]. |  | field if the validator doesn't match, resulting in transfer of the |
|  |  | new selected representation instead of a 412 response. If-Range is |
|  |  | defined in Section 3.2 of [Part5]. |
| 4. Status Code Definitions |  | 4. Status Code Definitions |
| 4.1. 304 Not Modified |  | 4.1. 304 Not Modified |
| The 304 (Not Modified) status code indicates that a conditional GET |  | The 304 (Not Modified) status code indicates that a conditional GET |
| or HEAD request has been received and would have resulted in a 200 |  | or HEAD request has been received and would have resulted in a 200 |
| (OK) response if it were not for the fact that the condition has |  | (OK) response if it were not for the fact that the condition has |
| evaluated to false. In other words, there is no need for the server |  | evaluated to false. In other words, there is no need for the server |
| to transfer a representation of the target resource because the |  | to transfer a representation of the target resource because the |
| request indicates that the client, which made the request |  | request indicates that the client, which made the request |
| conditional, already has a valid representation; the server is |  | conditional, already has a valid representation; the server is |
| therefore redirecting the client to make use of that stored |  | therefore redirecting the client to make use of that stored |
| representation as if it were the payload of a 200 (OK) response. |  | representation as if it were the payload of a 200 (OK) response. |
| The server generating a 304 response MUST generate any of the |  | The server generating a 304 response MUST generate any of the |
| following header fields that would have been sent in a 200 (OK) |  | following header fields that would have been sent in a 200 (OK) |
| response to the same request: Cache-Control, Content-Location, ETag, |  | response to the same request: Cache-Control, Content-Location, Date, |
| Expires, and Vary. |  | ETag, Expires, and Vary. |
| Since the goal of a 304 response is to minimize information transfer |  | Since the goal of a 304 response is to minimize information transfer |
| when the recipient already has one or more cached representations, a |  | when the recipient already has one or more cached representations, a |
| sender SHOULD NOT generate representation metadata other than the |  | sender SHOULD NOT generate representation metadata other than the |
| above listed fields unless said metadata exists for the purpose of |  | above listed fields unless said metadata exists for the purpose of |
| guiding cache updates (e.g., Last-Modified might be useful if the |  | guiding cache updates (e.g., Last-Modified might be useful if the |
| response does not have an ETag field). |  | response does not have an ETag field). |
| Requirements on a cache that receives a 304 response are defined in |  | Requirements on a cache that receives a 304 response are defined in |
| Section 4.2.1 of [Part6]. If the conditional request originated with |  | Section 4.3.4 of [Part6]. If the conditional request originated with |
| an outbound client, such as a user agent with its own cache sending a |  | an outbound client, such as a user agent with its own cache sending a |
| conditional GET to a shared proxy, then the proxy SHOULD forward the |  | conditional GET to a shared proxy, then the proxy SHOULD forward the |
| 304 response to that client. |  | 304 response to that client. |
| A 304 response cannot contain a message-body; it is always terminated |  | A 304 response cannot contain a message-body; it is always terminated |
| by the first empty line after the header fields. |  | by the first empty line after the header fields. |
| 4.2. 412 Precondition Failed |  | 4.2. 412 Precondition Failed |
| The 412 (Precondition Failed) status code indicates that one or more |  | The 412 (Precondition Failed) status code indicates that one or more |
| preconditions given in the request header fields evaluated to false |  | conditions given in the request header fields evaluated to false when |
| when tested on the server. This response code allows the client to |  | tested on the server. This response code allows the client to place |
| place preconditions on the current resource state (its current |  | preconditions on the current resource state (its current |
| representations and metadata) and thus prevent the request method |  | representations and metadata) and thus prevent the request method |
| from being applied if the target resource is in an unexpected state. |  | from being applied if the target resource is in an unexpected state. |
| 5. Evaluation and Precedence |  | 5. Evaluation |
| For each conditional request, a server MUST evaluate the request |  | Except when excluded below, a recipient cache or origin server MUST |
| preconditions after it has successfully performed its normal request |  | evaluate received request preconditions after it has successfully |
| checks (i.e., just before it would perform the action associated with |  | performed its normal request checks and just before it would perform |
| the request method). Preconditions are ignored if the server |  | the action associated with the request method. A server MUST ignore |
| determines that an error or redirect response applies before they are |  | all received preconditions if its response to the same request |
| evaluated. Otherwise, the evaluation depends on both the method |  | without those conditions would have been a status code other than a |
| semantics and the choice of conditional. |  | 2xx or 412 (Precondition Failed). In other words, redirects and |
|  |  | failures take precedence over the evaluation of preconditions in |
|  |  | conditional requests. |
| A conditional request header field that is designed specifically for |  | A server that is not the origin server for the target resource and |
| cache validation, which includes If-None-Match and If-Modified-Since |  | cannot act as a cache for requests on the target resource MUST NOT |
| when used in a GET or HEAD request, allows cached representations to |  | evaluate the conditional request header fields defined by this |
| be refreshed without repeatedly transferring data already held by the |  | specification, and MUST forward them if the request is forwarded, |
| client. Evaluating to false is thus an indication that the client |  | since the generating client intends that they be evaluated by a |
| can continue to use its local copy of the selected representation, as |  | server that can provide a current representation. Likewise, a server |
| indicated by the server generating a 304 (Not Modified) response that |  | MUST ignore the conditional request header fields defined by this |
| includes only those header fields useful for refreshing the cached |  | specification when received with a request method that does not |
| representation. |  | involve the selection or modification of a selected representation, |
|  |  | such as CONNECT, OPTIONS, or TRACE. |
| All other conditionals are intended to signal failure when the |  | Conditional request header fields that are defined by extensions to |
| precondition evaluates to false. For example, an If-Match |  | HTTP might place conditions on all recipients, on the state of the |
| conditional sent with a state-changing method (e.g., POST, PUT, |  | target resource in general, or on a group of resources. For |
| DELETE) is intended to prevent the request from taking effect on the |  | instance, the "If" header field in WebDAV can make a request |
| target resource if the resource state does not match the expected |  | conditional on various aspects of multiple resources, such as locks, |
| state. In other words, evaluating the condition to false means that |  | if the recipient understands and implements that field ([RFC4918], |
| the resource has been changed by some other client, perhaps by |  | Section 10.4). |
| another user attempting to edit the same resource, and thus |  |  |
| preventing the request from being applied saves the client from |  |  |
| overwriting some other client's work. This result is indicated by |  |  |
| the server generating a 412 (Precondition Failed) response. |  |  |
| The conditional request header fields defined by this specification |  | Although conditional request header fields are defined as being |
| are ignored for request methods that never involve the selection or |  | usable with the HEAD method (to keep HEAD's semantics consistent with |
| modification of a selected representation (e.g., CONNECT, OPTIONS, |  | those of GET), there is no point in sending a conditional HEAD |
| and TRACE). Other conditional request header fields, defined by |  | because a successful response is around the same size as a 304 (Not |
| extensions to HTTP, might place conditions on the state of the target |  | Modified) response and more useful than a 412 (Precondition Failed) |
| resource in general, or on a group of resources. For instance, the |  | response. |
| If header field in WebDAV can make a request conditional on various |  |  |
| aspects (such as locks) of multiple resources ([RFC4918], Section |  | 6. Precedence |
| 10.4). |  |  |
| When more than one conditional request header field is present in a |  | When more than one conditional request header field is present in a |
| request, the order in which the fields are evaluated becomes |  | request, the order in which the fields are evaluated becomes |
| important. In practice, the fields defined in this document are |  | important. In practice, the fields defined in this document are |
| consistently implemented in a single, logical order, due to the fact |  | consistently implemented in a single, logical order, since "lost |
| that entity tags are presumed to be more accurate than date |  | update" preconditions have more strict requirements than cache |
| validators. For example, the only reason to send both If-Modified- |  | validation, a validated cache is more efficient than a partial |
| Since and If-None-Match in the same GET request is to support |  | response, and entity tags are presumed to be more accurate than date |
| intermediary caches that might not have implemented If-None-Match, so |  | validators. |
| it makes sense to ignore the If-Modified-Since when entity tags are |  |  |
| understood and available for the selected representation. |  |  |
| The general rule of conditional precedence is that exact match |  |  |
| conditions are evaluated before cache-validating conditions and, |  |  |
| within that order, last-modified conditions are only evaluated if the |  |  |
| corresponding entity tag condition is not present (or not applicable |  |  |
| because the selected representation does not have an entity tag). |  |  |
| Specifically, the fields defined by this specification are evaluated |  | A recipient cache or origin server MUST evaluate the request |
| as follows: |  | preconditions defined by this specification in the following order: |
| 1. When If-Match is present, evaluate it: |  | 1. When recipient is the origin server and If-Match is present, |
|  |  | evaluate the If-Match precondition: |
| * if true, continue to step 3 |  | * if true, continue to step 3 |
| * if false, respond 412 (Precondition Failed) |  | * if false, respond 412 (Precondition Failed) unless it can be |
|  |  | determined that the state-changing request has already |
|  |  | succeeded (see Section 3.1) |
| 2. When If-Match is not present and If-Unmodified-Since is present, |  | 2. When recipient is the origin server, If-Match is not present, and |
| evaluate it: |  | If-Unmodified-Since is present, evaluate the If-Unmodified-Since |
|  |  | precondition: |
| * if true, continue to step 3 |  | * if true, continue to step 3 |
| * if false, respond 412 (Precondition Failed) |  | * if false, respond 412 (Precondition Failed) unless it can be |
|  |  | determined that the state-changing request has already |
|  |  | succeeded (see Section 3.4) |
| 3. When If-None-Match is present, evaluate it: |  | 3. When If-None-Match is present, evaluate the If-None-Match |
|  |  | precondition: |
| * if true, continue to step 5 |  | * if true, continue to step 5 |
| * if false for GET/HEAD, respond 304 (Not Modified) |  | * if false for GET/HEAD, respond 304 (Not Modified) |
| * if false for other methods, respond 412 (Precondition Failed) |  | * if false for other methods, respond 412 (Precondition Failed) |
| 4. When the method is GET or HEAD, If-None-Match is not present, and |  | 4. When the method is GET or HEAD, If-None-Match is not present, and |
| If-Modified-Since is present, evaluate it: |  | If-Modified-Since is present, evaluate the If-Modified-Since |
|  |  | precondition: |
| * if true, continue to step 5 |  | * if true, continue to step 5 |
| * if false, respond 304 (Not Modified) |  | * if false, respond 304 (Not Modified) |
| 5. When the method is GET and both Range and If-Range are present, |  | 5. When the method is GET and both Range and If-Range are present, |
| evaluate If-Range: |  | evaluate the If-Range precondition: |
| * if the validator matches and the Range specification is |  | * if the validator matches and the Range specification is |
| applicable to the selected representation, respond 206 |  | applicable to the selected representation, respond 206 |
| (Partial Content) [Part5] |  | (Partial Content) [Part5] |
| 6. Otherwise, |  | 6. Otherwise, |
| * all conditions are met, so perform the requested action and |  | * all conditions are met, so perform the requested action and |
| respond according to its success or failure. |  | respond according to its success or failure. |
| Any extension to HTTP/1.1 that defines additional conditional request |  | Any extension to HTTP/1.1 that defines additional conditional request |
| header fields ought to define its own expectations regarding the |  | header fields ought to define its own expectations regarding the |
| order for evaluating such fields in relation to those defined in this |  | order for evaluating such fields in relation to those defined in this |
| document and other conditionals that might be found in practice. |  | document and other conditionals that might be found in practice. |
| 6. IANA Considerations |  | 7. IANA Considerations |
| 6.1. Status Code Registration |  | 7.1. Status Code Registration |
| The HTTP Status Code Registry located at |  | The HTTP Status Code Registry located at |
| <http://www.iana.org/assignments/http-status-codes> shall be updated |  | <http://www.iana.org/assignments/http-status-codes> shall be updated |
| with the registrations below: |  | with the registrations below: |
| +-------+---------------------+-------------+ |  | +-------+---------------------+-------------+ |
| | Value | Description | Reference | |  | | Value | Description | Reference | |
| +-------+---------------------+-------------+ |  | +-------+---------------------+-------------+ |
| | 304 | Not Modified | Section 4.1 | |  | | 304 | Not Modified | Section 4.1 | |
| | 412 | Precondition Failed | Section 4.2 | |  | | 412 | Precondition Failed | Section 4.2 | |
| +-------+---------------------+-------------+ |  | +-------+---------------------+-------------+ |
| 6.2. Header Field Registration |  | 7.2. Header Field Registration |
| HTTP header fields are registered within the Message Header Field |  | HTTP header fields are registered within the Message Header Field |
| Registry maintained at <http://www.iana.org/assignments/ |  | Registry maintained at <http://www.iana.org/assignments/ |
| message-headers/message-header-index.html>. |  | message-headers/message-header-index.html>. |
| This document defines the following HTTP header fields, so their |  | This document defines the following HTTP header fields, so their |
| associated registry entries shall be updated according to the |  | associated registry entries shall be updated according to the |
| permanent registrations below (see [BCP90]): |  | permanent registrations below (see [BCP90]): |
| +---------------------+----------+----------+-------------+ |  | +---------------------+----------+----------+-------------+ |
| skipping to change at page 20, line 49 |  | skipping to change at page 22, line 19 |
| | If-Match | http | standard | Section 3.1 | |  | | If-Match | http | standard | Section 3.1 | |
| | If-Modified-Since | http | standard | Section 3.3 | |  | | If-Modified-Since | http | standard | Section 3.3 | |
| | If-None-Match | http | standard | Section 3.2 | |  | | If-None-Match | http | standard | Section 3.2 | |
| | If-Unmodified-Since | http | standard | Section 3.4 | |  | | If-Unmodified-Since | http | standard | Section 3.4 | |
| | Last-Modified | http | standard | Section 2.2 | |  | | Last-Modified | http | standard | Section 2.2 | |
| +---------------------+----------+----------+-------------+ |  | +---------------------+----------+----------+-------------+ |
| The change controller is: "IETF (iesg@ietf.org) - Internet |  | The change controller is: "IETF (iesg@ietf.org) - Internet |
| Engineering Task Force". |  | Engineering Task Force". |
| 7. Security Considerations |  | 8. Security Considerations |
| This section is meant to inform developers, information providers, |  | This section is meant to inform developers, information providers, |
| and users of known security concerns specific to the HTTP/1.1 |  | and users of known security concerns specific to the HTTP/1.1 |
| conditional request mechanisms. More general security considerations |  | conditional request mechanisms. More general security considerations |
| are addressed in HTTP messaging [Part1] and semantics [Part2]. |  | are addressed in HTTP messaging [Part1] and semantics [Part2]. |
| The validators defined by this specification are not intended to |  | The validators defined by this specification are not intended to |
| ensure the validity of a representation, guard against malicious |  | ensure the validity of a representation, guard against malicious |
| changes, or detect man-in-the-middle attacks. At best, they enable |  | changes, or detect man-in-the-middle attacks. At best, they enable |
| more efficient cache updates and optimistic concurrent writes when |  | more efficient cache updates and optimistic concurrent writes when |
| skipping to change at page 21, line 27 |  | skipping to change at page 22, line 46 |
| entity-tag that is unique to the user or user agent, send it in a |  | entity-tag that is unique to the user or user agent, send it in a |
| cacheable response with a long freshness time, and then read that |  | cacheable response with a long freshness time, and then read that |
| entity-tag in later conditional requests as a means of re-identifying |  | entity-tag in later conditional requests as a means of re-identifying |
| that user or user agent. Such an identifying tag would become a |  | that user or user agent. Such an identifying tag would become a |
| persistent identifier for as long as the user agent retained the |  | persistent identifier for as long as the user agent retained the |
| original cache entry. User agents that cache representations ought |  | original cache entry. User agents that cache representations ought |
| to ensure that the cache is cleared or replaced whenever the user |  | to ensure that the cache is cleared or replaced whenever the user |
| performs privacy-maintaining actions, such as clearing stored cookies |  | performs privacy-maintaining actions, such as clearing stored cookies |
| or changing to a private browsing mode. |  | or changing to a private browsing mode. |
| 8. Acknowledgments |  | 9. Acknowledgments |
| See Section 9 of [Part1]. |  |  |
| 9. References |  | See Section 10 of [Part1]. |
| 9.1. Normative References |  | 10. References |
|  |  | 10.1. Normative References |
| [Part1] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer |  | [Part1] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer |
| Protocol (HTTP/1.1): Message Syntax and Routing", |  | Protocol (HTTP/1.1): Message Syntax and Routing", |
| draft-ietf-httpbis-p1-messaging-23 (work in progress), |  | draft-ietf-httpbis-p1-messaging-24 (work in progress), |
| July 2013. |  | September 2013. |
| [Part2] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer |  | [Part2] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer |
| Protocol (HTTP/1.1): Semantics and Content", |  | Protocol (HTTP/1.1): Semantics and Content", |
| draft-ietf-httpbis-p2-semantics-23 (work in progress), |  | draft-ietf-httpbis-p2-semantics-24 (work in progress), |
| July 2013. |  | September 2013. |
| [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |  | [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
| "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", |  | "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", |
| draft-ietf-httpbis-p5-range-23 (work in progress), |  | draft-ietf-httpbis-p5-range-24 (work in progress), |
| July 2013. |  | September 2013. |
| [Part6] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, |  | [Part6] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, |
| Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", |  | Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", |
| draft-ietf-httpbis-p6-cache-23 (work in progress), |  | draft-ietf-httpbis-p6-cache-24 (work in progress), |
| July 2013. |  | September 2013. |
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |  | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |
| Requirement Levels", BCP 14, RFC 2119, March 1997. |  | Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax |  | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax |
| Specifications: ABNF", STD 68, RFC 5234, January 2008. |  | Specifications: ABNF", STD 68, RFC 5234, January 2008. |
| 9.2. Informative References |  | 10.2. Informative References |
| [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration |  | [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration |
| Procedures for Message Header Fields", BCP 90, RFC 3864, |  | Procedures for Message Header Fields", BCP 90, RFC 3864, |
| September 2004. |  | September 2004. |
| [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |  | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |  | Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |
| Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |  | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
| [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed |  | [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed |
| Authoring and Versioning (WebDAV)", RFC 4918, June 2007. |  | Authoring and Versioning (WebDAV)", RFC 4918, June 2007. |
| Appendix A. Changes from RFC 2616 |  | Appendix A. Changes from RFC 2616 |
| The definition of validator weakness has been expanded and clarified. |  | The definition of validator weakness has been expanded and clarified. |
| (Section 2.1) |  | (Section 2.1) |
| Weak entity-tags are now allowed in all requests except range |  | Weak entity-tags are now allowed in all requests except range |
| requests (Sections 2.1 and 3.2). |  | requests. (Sections 2.1 and 3.2) |
| The ETag header field ABNF has been changed to not use quoted-string, |  | The ETag header field ABNF has been changed to not use quoted-string, |
| thus avoiding escaping issues. (Section 2.3) |  | thus avoiding escaping issues. (Section 2.3) |
| ETag is defined to provide an entity tag for the selected |  | ETag is defined to provide an entity tag for the selected |
| representation, thereby clarifying what it applies to in various |  | representation, thereby clarifying what it applies to in various |
| situations (such as a PUT response). (Section 2.3) |  | situations (such as a PUT response). (Section 2.3) |
| The precedence for evaluation of conditional requests has been |  | The precedence for evaluation of conditional requests has been |
| defined. (Section 5) |  | defined. (Section 6) |
| Appendix B. Imported ABNF |  | Appendix B. Imported ABNF |
| The following core rules are included by reference, as defined in |  | The following core rules are included by reference, as defined in |
| Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), |  | Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), |
| CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double |  | CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double |
| quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any |  | quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any |
| 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII |  | 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII |
| character). |  | character). |
| skipping to change at page 25, line 29 |  | skipping to change at page 27, line 13 |
| expansion in ABNF appendices" |  | expansion in ABNF appendices" |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/437>: "incorrect |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/437>: "incorrect |
| example dates" |  | example dates" |
| Partly resolved issues: |  | Partly resolved issues: |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/461>: "Editorial |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/461>: "Editorial |
| suggestions" |  | suggestions" |
|  |  | D.5. Since draft-ietf-httpbis-p4-conditional-23 |
|  |  | Closed issues: |
|  |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/455>: "PUT + If- |
|  |  | Match over-constrained?" |
|  |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/479>: "MUSTs and |
|  |  | other feedback" |
|  |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/495>: "p4 editorial |
|  |  | nits" |
| Index |  | Index |
| 3 |  | 3 |
| 304 Not Modified (status code) 17 |  | 304 Not Modified (status code) 18 |
| 4 |  | 4 |
| 412 Precondition Failed (status code) 17 |  | 412 Precondition Failed (status code) 18 |
| E |  | E |
| ETag header field 9 |  | ETag header field 9 |
| G |  | G |
| Grammar |  | Grammar |
| entity-tag 9 |  | entity-tag 9 |
| ETag 9 |  | ETag 9 |
| etagc 9 |  | etagc 9 |
| If-Match 13 |  | If-Match 13 |
End of changes. 70 change blocks.
| 239 lines changed or deleted |  | 308 lines changed or added |
This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/