draft-ietf-httpbis-p4-conditional-22.txt   draft-ietf-httpbis-p4-conditional-23.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: August 27, 2013 February 23, 2013 Expires: January 16, 2014 July 15, 2013
Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests
draft-ietf-httpbis-p4-conditional-22 draft-ietf-httpbis-p4-conditional-23
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.3. The changes in this draft are summarized in Appendix D.4.
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 August 27, 2013. This Internet-Draft will expire on January 16, 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 47 skipping to change at page 3, line 47
9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21
9.2. Informative References . . . . . . . . . . . . . . . . . . 22 9.2. Informative References . . . . . . . . . . . . . . . . . . 22
Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 22 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 22
Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 22 Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 22
Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 23 Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 23
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) . . . . . . . . . . . . . . . . . . . . 23
D.1. Since draft-ietf-httpbis-p4-conditional-19 . . . . . . . . 23 D.1. Since draft-ietf-httpbis-p4-conditional-19 . . . . . . . . 23
D.2. Since draft-ietf-httpbis-p4-conditional-20 . . . . . . . . 24 D.2. Since draft-ietf-httpbis-p4-conditional-20 . . . . . . . . 24
D.3. Since draft-ietf-httpbis-p4-conditional-21 . . . . . . . . 24 D.3. Since draft-ietf-httpbis-p4-conditional-21 . . . . . . . . 24
D.4. Since draft-ietf-httpbis-p4-conditional-22 . . . . . . . . 25
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
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 6, line 13 skipping to change at page 6, line 13
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 SHOULD incorporate additional
information in the validator to distinguish those representations and information in the validator to distinguish those representations.
avoid confusing cache behavior.
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
representations to be unacceptable as a substitute for the current representations to be unacceptable as a substitute for the current
skipping to change at page 11, line 24 skipping to change at page 11, line 24
GET /index HTTP/1.1 GET /index HTTP/1.1
Host: www.example.com Host: www.example.com
Accept-Encoding: gzip Accept-Encoding: gzip
In this case, the response might or might not use the gzip content In this case, the response might or might not use the gzip content
coding. If it does not, the response might look like: coding. If it does not, the response might look like:
>> Response: >> Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Thu, 26 Mar 2010 00:05:00 GMT Date: Fri, 26 Mar 2010 00:05:00 GMT
ETag: "123-a" ETag: "123-a"
Content-Length: 70 Content-Length: 70
Vary: Accept-Encoding Vary: Accept-Encoding
Content-Type: text/plain Content-Type: text/plain
Hello World! Hello World!
Hello World! Hello World!
Hello World! Hello World!
Hello World! Hello World!
Hello World! Hello World!
An alternative representation that does use gzip content coding would An alternative representation that does use gzip content coding would
be: be:
>> Response: >> Response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Date: Thu, 26 Mar 2010 00:05:00 GMT Date: Fri, 26 Mar 2010 00:05:00 GMT
ETag: "123-b" ETag: "123-b"
Content-Length: 43 Content-Length: 43
Vary: Accept-Encoding Vary: Accept-Encoding
Content-Type: text/plain Content-Type: text/plain
Content-Encoding: gzip Content-Encoding: gzip
...binary data... ...binary data...
Note: Content codings are a property of the representation, so Note: Content codings are a property of the representation, so
therefore an entity-tag of an encoded representation has to be therefore an entity-tag of an encoded representation has to be
skipping to change at page 14, line 22 skipping to change at page 14, line 22
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. A client that has one or more representations
previously obtained from the target resource can send If-None-Match previously obtained from the target resource can send If-None-Match
with a list of the associated entity-tags in the hope of receiving a with a list of the associated entity-tags in the hope of receiving a
304 (Not Modified) response if at least one of those representations 304 (Not Modified) response if at least one of those representations
matches the selected representation. 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
This is a variation on the "lost update" problem that might arise if (Section 4.2.1 of [Part2]). This is a variation on the "lost update"
more than one client attempts to create an initial representation for problem that might arise if more than one client attempts to create
the target resource. an initial representation for the target resource.
If-None-Match = "*" / 1#entity-tag If-None-Match = "*" / 1#entity-tag
The If-None-Match condition is met if and only if none of the entity- The If-None-Match condition is met if and only if none of the entity-
tags listed in the If-None-Match field value match the entity-tag of tags listed in the If-None-Match field value match the entity-tag of
the selected representation using the weak comparison function (as the selected representation using the weak comparison function (as
per Section 2.3.2), or if "*" is given and no current representation per Section 2.3.2), or if "*" is given and no current representation
exists for that resource. exists for that resource.
If the condition is not met, the server MUST NOT perform the If the condition is not met, the server MUST NOT perform the
skipping to change at page 17, line 10 skipping to change at page 17, line 10
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 If-Match and If-Unmodified-Since but
specific to range requests. If-Range is defined in Section 3.2 of specific to range requests. If-Range is defined in Section 3.2 of
[Part5]. [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
request has been received and would have resulted in a 200 (OK) or HEAD request has been received and would have resulted in a 200
response if it were not for the fact that the condition has evaluated (OK) response if it were not for the fact that the condition has
to false. In other words, there is no need for the server to evaluated to false. In other words, there is no need for the server
transfer a representation of the target resource because the request to transfer a representation of the target resource because the
indicates that the client, which made the request conditional, request indicates that the client, which made the request
already has a valid representation; the server is therefore conditional, already has a valid representation; the server is
redirecting the client to make use of that stored representation as therefore redirecting the client to make use of that stored
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, ETag,
Expires, and Vary. 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
skipping to change at page 20, line 27 skipping to change at page 20, line 27
+-------+---------------------+-------------+ +-------+---------------------+-------------+
| 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 6.2. Header Field Registration
The Message Header Field Registry located at <http://www.iana.org/ HTTP header fields are registered within the Message Header Field
assignments/message-headers/message-header-index.html> shall be Registry maintained at <http://www.iana.org/assignments/
updated with the permanent registrations below (see [BCP90]): message-headers/message-header-index.html>.
This document defines the following HTTP header fields, so their
associated registry entries shall be updated according to the
permanent registrations below (see [BCP90]):
+---------------------+----------+----------+-------------+ +---------------------+----------+----------+-------------+
| Header Field Name | Protocol | Status | Reference | | Header Field Name | Protocol | Status | Reference |
+---------------------+----------+----------+-------------+ +---------------------+----------+----------+-------------+
| ETag | http | standard | Section 2.3 | | ETag | http | standard | Section 2.3 |
| 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 |
skipping to change at page 21, line 33 skipping to change at page 21, line 37
8. Acknowledgments 8. Acknowledgments
See Section 9 of [Part1]. See Section 9 of [Part1].
9. References 9. References
9.1. Normative References 9.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-22 (work in progress), draft-ietf-httpbis-p1-messaging-23 (work in progress),
February 2013. July 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-22 (work in progress), draft-ietf-httpbis-p2-semantics-23 (work in progress),
February 2013. July 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-22 (work in progress), draft-ietf-httpbis-p5-range-23 (work in progress),
February 2013. July 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-22 (work in progress), draft-ietf-httpbis-p6-cache-23 (work in progress),
February 2013. July 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 9.2. Informative References
[BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
skipping to change at page 23, line 12 skipping to change at page 23, line 16
OWS = <OWS, defined in [Part1], Section 3.2.3> OWS = <OWS, defined in [Part1], Section 3.2.3>
obs-text = <obs-text, defined in [Part1], Section 3.2.6> obs-text = <obs-text, defined in [Part1], Section 3.2.6>
The rules below are defined in other parts: The rules below are defined in other parts:
HTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1> HTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1>
Appendix C. Collected ABNF Appendix C. Collected ABNF
In the collected ABNF below, list rules are expanded as per Section
1.2 of [Part1].
ETag = entity-tag ETag = entity-tag
HTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1> HTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1>
If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS
entity-tag ] ) ) entity-tag ] ) )
If-Modified-Since = HTTP-date If-Modified-Since = HTTP-date
If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS
entity-tag ] ) ) entity-tag ] ) )
If-Unmodified-Since = HTTP-date If-Unmodified-Since = HTTP-date
skipping to change at page 25, line 8 skipping to change at page 25, line 14
o <http://tools.ietf.org/wg/httpbis/trac/ticket/402>: "Comparison o <http://tools.ietf.org/wg/httpbis/trac/ticket/402>: "Comparison
function for If-Match and If-None-Match" function for If-Match and If-None-Match"
o <http://tools.ietf.org/wg/httpbis/trac/ticket/406>: "304 without o <http://tools.ietf.org/wg/httpbis/trac/ticket/406>: "304 without
validator" validator"
o <http://tools.ietf.org/wg/httpbis/trac/ticket/427>: "If-Match and o <http://tools.ietf.org/wg/httpbis/trac/ticket/427>: "If-Match and
428" 428"
D.4. Since draft-ietf-httpbis-p4-conditional-22
Closed issues:
o <http://tools.ietf.org/wg/httpbis/trac/ticket/436>: "explain list
expansion in ABNF appendices"
o <http://tools.ietf.org/wg/httpbis/trac/ticket/437>: "incorrect
example dates"
Partly resolved issues:
o <http://tools.ietf.org/wg/httpbis/trac/ticket/461>: "Editorial
suggestions"
Index Index
3 3
304 Not Modified (status code) 17 304 Not Modified (status code) 17
4 4
412 Precondition Failed (status code) 17 412 Precondition Failed (status code) 17
E E
ETag header field 9 ETag header field 9
 End of changes. 17 change blocks. 
31 lines changed or deleted 53 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/