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.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |