idnits 2.17.1 draft-ietf-httpbis-p4-conditional-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 11, 2011) is 4665 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-15 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-15 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-15 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-15 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Fielding, Ed. 3 Internet-Draft Adobe 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track Alcatel-Lucent 6 Expires: January 12, 2012 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 Y. Lafon, Ed. 17 W3C 18 J. Reschke, Ed. 19 greenbytes 20 July 11, 2011 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-15 25 Abstract 27 The Hypertext Transfer Protocol (HTTP) is an application-level 28 protocol for distributed, collaborative, hypermedia information 29 systems. HTTP has been in use by the World Wide Web global 30 information initiative since 1990. This document is Part 4 of the 31 seven-part specification that defines the protocol referred to as 32 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 4 defines 33 request header fields for indicating conditional requests and the 34 rules for constructing responses to those requests. 36 Editorial Note (To be removed by RFC Editor) 38 Discussion of this draft should take place on the HTTPBIS working 39 group mailing list (ietf-http-wg@w3.org), which is archived at 40 . 42 The current issues list is at 43 and related 44 documents (including fancy diffs) can be found at 45 . 47 The changes in this draft are summarized in Appendix C.16. 49 Status of This Memo 51 This Internet-Draft is submitted in full conformance with the 52 provisions of BCP 78 and BCP 79. 54 Internet-Drafts are working documents of the Internet Engineering 55 Task Force (IETF). Note that other groups may also distribute 56 working documents as Internet-Drafts. The list of current Internet- 57 Drafts is at http://datatracker.ietf.org/drafts/current/. 59 Internet-Drafts are draft documents valid for a maximum of six months 60 and may be updated, replaced, or obsoleted by other documents at any 61 time. It is inappropriate to use Internet-Drafts as reference 62 material or to cite them other than as "work in progress." 64 This Internet-Draft will expire on January 12, 2012. 66 Copyright Notice 68 Copyright (c) 2011 IETF Trust and the persons identified as the 69 document authors. All rights reserved. 71 This document is subject to BCP 78 and the IETF Trust's Legal 72 Provisions Relating to IETF Documents 73 (http://trustee.ietf.org/license-info) in effect on the date of 74 publication of this document. Please review these documents 75 carefully, as they describe your rights and restrictions with respect 76 to this document. Code Components extracted from this document must 77 include Simplified BSD License text as described in Section 4.e of 78 the Trust Legal Provisions and are provided without warranty as 79 described in the Simplified BSD License. 81 This document may contain material from IETF Documents or IETF 82 Contributions published or made publicly available before November 83 10, 2008. The person(s) controlling the copyright in some of this 84 material may not have granted the IETF Trust the right to allow 85 modifications of such material outside the IETF Standards Process. 86 Without obtaining an adequate license from the person(s) controlling 87 the copyright in such materials, this document may not be modified 88 outside the IETF Standards Process, and derivative works of it may 89 not be created outside the IETF Standards Process, except to format 90 it for publication as an RFC or to translate it into languages other 91 than English. 93 Table of Contents 95 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 96 1.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 5 97 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 6 98 2. Resource State Metadata (Validators) . . . . . . . . . . . . . 6 99 2.1. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 6 100 2.1.1. Generation . . . . . . . . . . . . . . . . . . . . . . 6 101 2.1.2. Comparison . . . . . . . . . . . . . . . . . . . . . . 7 102 2.2. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 103 2.2.1. Generation . . . . . . . . . . . . . . . . . . . . . . 9 104 2.2.2. Weak versus Strong . . . . . . . . . . . . . . . . . . 9 105 2.2.3. Comparison . . . . . . . . . . . . . . . . . . . . . . 11 106 2.2.4. Rules for When to Use Entity-tags and 107 Last-Modified Dates . . . . . . . . . . . . . . . . . 11 108 2.2.5. Example: Entity-tags varying on Content-Negotiated 109 Resources . . . . . . . . . . . . . . . . . . . . . . 13 110 3. Precondition Header Fields . . . . . . . . . . . . . . . . . . 14 111 3.1. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 14 112 3.2. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 15 113 3.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 16 114 3.4. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 18 115 3.5. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 18 116 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 18 117 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 18 118 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 19 119 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 120 5.1. Status Code Registration . . . . . . . . . . . . . . . . . 19 121 5.2. Header Field Registration . . . . . . . . . . . . . . . . 20 122 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 123 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 124 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 125 8.1. Normative References . . . . . . . . . . . . . . . . . . . 20 126 8.2. Informative References . . . . . . . . . . . . . . . . . . 21 127 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 21 128 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 22 129 Appendix C. Change Log (to be removed by RFC Editor before 130 publication) . . . . . . . . . . . . . . . . . . . . 22 131 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 22 132 C.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 22 133 C.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 23 134 C.4. Since draft-ietf-httpbis-p4-conditional-02 . . . . . . . . 23 135 C.5. Since draft-ietf-httpbis-p4-conditional-03 . . . . . . . . 23 136 C.6. Since draft-ietf-httpbis-p4-conditional-04 . . . . . . . . 23 137 C.7. Since draft-ietf-httpbis-p4-conditional-05 . . . . . . . . 24 138 C.8. Since draft-ietf-httpbis-p4-conditional-06 . . . . . . . . 24 139 C.9. Since draft-ietf-httpbis-p4-conditional-07 . . . . . . . . 24 140 C.10. Since draft-ietf-httpbis-p4-conditional-08 . . . . . . . . 24 141 C.11. Since draft-ietf-httpbis-p4-conditional-09 . . . . . . . . 24 142 C.12. Since draft-ietf-httpbis-p4-conditional-10 . . . . . . . . 24 143 C.13. Since draft-ietf-httpbis-p4-conditional-11 . . . . . . . . 25 144 C.14. Since draft-ietf-httpbis-p4-conditional-12 . . . . . . . . 25 145 C.15. Since draft-ietf-httpbis-p4-conditional-13 . . . . . . . . 25 146 C.16. Since draft-ietf-httpbis-p4-conditional-14 . . . . . . . . 25 147 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 149 1. Introduction 151 This document defines the HTTP/1.1 conditional request mechanisms, 152 including both response metadata that can be used to indicate or 153 observe changes to resource state and request header fields that 154 specify preconditions to be checked before performing the action 155 given by the request method. Conditional GET requests are the most 156 efficient mechanism for HTTP cache updates [Part6]. Conditionals can 157 also be applied to state-changing methods, such as PUT and DELETE, to 158 prevent the "lost update" problem: one client accidentally 159 overwriting the work of another client that has been acting in 160 parallel. 162 Conditional request preconditions are based on the state of the 163 target resource as a whole (its current value set) or the state as 164 observed in a previously obtained representation (one value in that 165 set). A resource might have multiple current representations, each 166 with its own observable state. The conditional request mechanisms 167 assume that the mapping of requests to corresponding representations 168 will be consistent over time if the server intends to take advantage 169 of conditionals. Regardless, if the mapping is inconsistent and the 170 server is unable to select the appropriate representation, then no 171 harm will result when the precondition evaluates to false. 173 We use the term "selected representation" to refer to the current 174 representation of the target resource that would have been selected 175 in a successful response if the same request had used the method GET 176 and had excluded all of the conditional request header fields. The 177 conditional request preconditions are evaluated by comparing the 178 values provided in the request header fields to the current metadata 179 for the selected representation. 181 1.1. Requirements 183 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 184 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 185 document are to be interpreted as described in [RFC2119]. 187 An implementation is not compliant if it fails to satisfy one or more 188 of the "MUST" or "REQUIRED" level requirements for the protocols it 189 implements. An implementation that satisfies all the "MUST" or 190 "REQUIRED" level and all the "SHOULD" level requirements for its 191 protocols is said to be "unconditionally compliant"; one that 192 satisfies all the "MUST" level requirements but not all the "SHOULD" 193 level requirements for its protocols is said to be "conditionally 194 compliant". 196 1.2. Syntax Notation 198 This specification uses the ABNF syntax defined in Section 1.2 of 199 [Part1] (which extends the syntax defined in [RFC5234] with a list 200 rule). Appendix B shows the collected ABNF, with the list rule 201 expanded. 203 The following core rules are included by reference, as defined in 204 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 205 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 206 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 207 sequence of data), SP (space), VCHAR (any visible USASCII character), 208 and WSP (whitespace). 210 The ABNF rules below are defined in other parts: 212 quoted-string = 213 OWS = 214 HTTP-date = 216 2. Resource State Metadata (Validators) 218 This specification defines two forms of metadata that are commonly 219 used to observe resource state and test for preconditions: 220 modification dates and opaque entity tags. Additional metadata that 221 reflects resource state has been defined by various extensions of 222 HTTP, such as WebDAV [RFC4918], that are beyond the scope of this 223 specification. A resource metadata value is referred to as a 224 "validator" when it is used within a precondition. 226 2.1. Last-Modified 228 The "Last-Modified" header field indicates the date and time at which 229 the origin server believes the selected representation was last 230 modified. 232 Last-Modified = HTTP-date 234 An example of its use is 236 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 238 2.1.1. Generation 240 Origin servers SHOULD send Last-Modified for any selected 241 representation for which a last modification date can be reasonably 242 and consistently determined, since its use in conditional requests 243 and evaluating cache freshness ([Part6]) results in a substantial 244 reduction of HTTP traffic on the Internet and can be a significant 245 factor in improving service scalability and reliability. 247 A representation is typically the sum of many parts behind the 248 resource interface. The last-modified time would usually be the most 249 recent time that any of those parts were changed. How that value is 250 determined for any given resource is an implementation detail beyond 251 the scope of this specification. What matters to HTTP is how 252 recipients of the Last-Modified header field can use its value to 253 make conditional requests and test the validity of locally cached 254 responses. 256 An origin server SHOULD obtain the Last-Modified value of the 257 representation as close as possible to the time that it generates the 258 Date field-value for its response. This allows a recipient to make 259 an accurate assessment of the representation's modification time, 260 especially if the representation changes near the time that the 261 response is generated. 263 An origin server with a clock MUST NOT send a Last-Modified date that 264 is later than the server's time of message origination (Date). If 265 the last modification time is derived from implementation-specific 266 metadata that evaluates to some time in the future, according to the 267 origin server's clock, then the origin server MUST replace that value 268 with the message origination date. This prevents a future 269 modification date from having an adverse impact on cache validation. 271 2.1.2. Comparison 273 A Last-Modified time, when used as a validator in a request, is 274 implicitly weak unless it is possible to deduce that it is strong, 275 using the following rules: 277 o The validator is being compared by an origin server to the actual 278 current validator for the representation and, 280 o That origin server reliably knows that the associated 281 representation did not change twice during the second covered by 282 the presented validator. 284 or 286 o The validator is about to be used by a client in an If-Modified- 287 Since or If-Unmodified-Since header field, because the client has 288 a cache entry for the associated representation, and 290 o That cache entry includes a Date value, which gives the time when 291 the origin server sent the original response, and 293 o The presented Last-Modified time is at least 60 seconds before the 294 Date value. 296 or 298 o The validator is being compared by an intermediate cache to the 299 validator stored in its cache entry for the representation, and 301 o That cache entry includes a Date value, which gives the time when 302 the origin server sent the original response, and 304 o The presented Last-Modified time is at least 60 seconds before the 305 Date value. 307 This method relies on the fact that if two different responses were 308 sent by the origin server during the same second, but both had the 309 same Last-Modified time, then at least one of those responses would 310 have a Date value equal to its Last-Modified time. The arbitrary 60- 311 second limit guards against the possibility that the Date and Last- 312 Modified values are generated from different clocks, or at somewhat 313 different times during the preparation of the response. An 314 implementation MAY use a value larger than 60 seconds, if it is 315 believed that 60 seconds is too short. 317 2.2. ETag 319 The ETag header field provides the current entity-tag for the 320 selected representation. An entity-tag is an opaque validator for 321 differentiating between multiple representations of the same 322 resource, regardless of whether those multiple representations are 323 due to resource state changes over time, content negotiation 324 resulting in multiple representations being valid at the same time, 325 or both. An entity-tag consists of an opaque quoted string, possibly 326 prefixed by a weakness indicator. 328 ETag = entity-tag 330 entity-tag = [ weak ] opaque-tag 331 weak = %x57.2F ; "W/", case-sensitive 332 opaque-tag = quoted-string 334 An entity-tag can be more reliable for validation than a modification 335 date in situations where it is inconvenient to store modification 336 dates, where the one-second resolution of HTTP date values is not 337 sufficient, or where modification dates are not consistently 338 maintained. 340 Examples: 342 ETag: "xyzzy" 343 ETag: W/"xyzzy" 344 ETag: "" 346 2.2.1. Generation 348 The principle behind entity-tags is that only the service author 349 knows the implementation of a resource well enough to select the most 350 accurate and efficient validation mechanism for that resource, and 351 that any such mechanism can be mapped to a simple sequence of octets 352 for easy comparison. Since the value is opaque, there is no need for 353 the client to be aware of how each entity-tag is constructed. 355 For example, a resource that has implementation-specific versioning 356 applied to all changes might use an internal revision number, perhaps 357 combined with a variance identifier for content negotiation, to 358 accurately differentiate between representations. Other 359 implementations might use a stored hash of representation content, a 360 combination of various filesystem attributes, or a modification 361 timestamp that has sub-second resolution. 363 Origin servers SHOULD send ETag for any selected representation for 364 which detection of changes can be reasonably and consistently 365 determined, since the entity-tag's use in conditional requests and 366 evaluating cache freshness ([Part6]) can result in a substantial 367 reduction of HTTP network traffic and can be a significant factor in 368 improving service scalability and reliability. 370 2.2.2. Weak versus Strong 372 Since both origin servers and caches will compare two validators to 373 decide if they indicate the same or different representations, one 374 normally would expect that if the representation (including both 375 representation header fields and representation body) changes in any 376 way, then the associated validator would change as well. If this is 377 true, then we call that validator a "strong validator". One example 378 of a strong validator is an integer that is incremented in stable 379 storage every time a representation is changed. 381 However, there might be cases when a server prefers to change the 382 validator only when it desires cached representations to be 383 invalidated. For example, the representation of a weather report 384 that changes in content every second, based on dynamic measurements, 385 might be grouped into sets of equivalent representations (from the 386 origin server's perspective) in order to allow cached representations 387 to be valid for a reasonable period of time (perhaps adjusted 388 dynamically based on server load or weather quality). A validator 389 that does not always change when the representation changes is a 390 "weak validator". 392 One can think of a strong validator as part of an identifier for a 393 specific representation, whereas a weak validator is part of an 394 identifier for a set of equivalent representations (where this notion 395 of equivalence is entirely governed by the origin server and beyond 396 the scope of this specification). 398 An entity-tag is normally a strong validator, but the protocol 399 provides a mechanism to tag an entity-tag as "weak". 401 A representation's modification time, if defined with only one- 402 second resolution, could be a weak validator, since it is possible 403 that the representation might be modified twice during a single 404 second. 406 Support for weak validators is optional. However, weak validators 407 allow for more efficient caching of equivalent objects; for 408 example, a hit counter on a site is probably good enough if it is 409 updated every few days or weeks, and any value during that period 410 is likely "good enough" to be equivalent. 412 A strong entity-tag MUST change whenever the associated 413 representation changes in any way. A weak entity-tag SHOULD change 414 whenever the origin server considers prior representations to be 415 unacceptable as a substitute for the current representation. In 416 other words, a weak entity tag SHOULD change whenever the origin 417 server wants caches to invalidate old responses. 419 A "strong entity-tag" MAY be shared by two representations of a 420 resource only if they are equivalent by octet equality. 422 A "weak entity-tag", indicated by the "W/" prefix, MAY be shared by 423 two representations of a resource. A weak entity-tag can only be 424 used for weak comparison. 426 Cache entries might persist for arbitrarily long periods, regardless 427 of expiration times. Thus, a cache might attempt to validate an 428 entry using a validator that it obtained in the distant past. A 429 strong entity-tag MUST be unique across all versions of all 430 representations associated with a particular resource over time. 431 However, there is no implication of uniqueness across entity-tags of 432 different resources (i.e., the same entity-tag value might be in use 433 for representations of multiple resources at the same time and does 434 not imply that those representations are equivalent). 436 2.2.3. Comparison 438 There are two entity-tag comparison functions, depending on whether 439 the comparison context allows the use of weak validators or not: 441 o The strong comparison function: in order to be considered equal, 442 both opaque-tags MUST be identical character-by-character, and 443 both MUST NOT be weak. 445 o The weak comparison function: in order to be considered equal, 446 both opaque-tags MUST be identical character-by-character, but 447 either or both of them MAY be tagged as "weak" without affecting 448 the result. 450 A "use" of a validator is either when a client generates a request 451 and includes the validator in a precondition, or when a server 452 compares two validators. 454 Strong validators are usable in any context. Weak validators are 455 only usable in contexts that do not depend on exact equality of a 456 representation. For example, either kind is usable for a normal 457 conditional GET. 459 The example below shows the results for a set of entity-tag pairs, 460 and both the weak and strong comparison function results: 462 +--------+--------+-------------------+-----------------+ 463 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 464 +--------+--------+-------------------+-----------------+ 465 | W/"1" | W/"1" | no match | match | 466 | W/"1" | W/"2" | no match | no match | 467 | W/"1" | "1" | no match | match | 468 | "1" | "1" | match | match | 469 +--------+--------+-------------------+-----------------+ 471 An entity-tag is strong unless it is explicitly tagged as weak. 473 2.2.4. Rules for When to Use Entity-tags and Last-Modified Dates 475 We adopt a set of rules and recommendations for origin servers, 476 clients, and caches regarding when various validator types ought to 477 be used, and for what purposes. 479 HTTP/1.1 origin servers: 481 o SHOULD send an entity-tag validator unless it is not feasible to 482 generate one. 484 o MAY send a weak entity-tag instead of a strong entity-tag, if 485 performance considerations support the use of weak entity-tags, or 486 if it is unfeasible to send a strong entity-tag. 488 o SHOULD send a Last-Modified value if it is feasible to send one. 490 In other words, the preferred behavior for an HTTP/1.1 origin server 491 is to send both a strong entity-tag and a Last-Modified value. 493 HTTP/1.1 clients: 495 o MUST use that entity-tag in any cache-conditional request (using 496 If-Match or If-None-Match) if an entity-tag has been provided by 497 the origin server. 499 o SHOULD use the Last-Modified value in non-subrange cache- 500 conditional requests (using If-Modified-Since) if only a Last- 501 Modified value has been provided by the origin server. 503 o MAY use the Last-Modified value in subrange cache-conditional 504 requests (using If-Unmodified-Since) if only a Last-Modified value 505 has been provided by an HTTP/1.0 origin server. The user agent 506 SHOULD provide a way to disable this, in case of difficulty. 508 o SHOULD use both validators in cache-conditional requests if both 509 an entity-tag and a Last-Modified value have been provided by the 510 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 511 respond appropriately. 513 An HTTP/1.1 origin server, upon receiving a conditional request that 514 includes both a Last-Modified date (e.g., in an If-Modified-Since or 515 If-Unmodified-Since header field) and one or more entity-tags (e.g., 516 in an If-Match, If-None-Match, or If-Range header field) as cache 517 validators, MUST NOT return a response status code of 304 (Not 518 Modified) unless doing so is consistent with all of the conditional 519 header fields in the request. 521 An HTTP/1.1 caching proxy, upon receiving a conditional request that 522 includes both a Last-Modified date and one or more entity-tags as 523 cache validators, MUST NOT return a locally cached response to the 524 client unless that cached response is consistent with all of the 525 conditional header fields in the request. 527 Note: The general principle behind these rules is that HTTP/1.1 528 servers and clients ought to transmit as much non-redundant 529 information as is available in their responses and requests. 530 HTTP/1.1 systems receiving this information will make the most 531 conservative assumptions about the validators they receive. 533 HTTP/1.0 clients and caches might ignore entity-tags. Generally, 534 last-modified values received or used by these systems will 535 support transparent and efficient caching, and so HTTP/1.1 origin 536 servers should provide Last-Modified values. In those rare cases 537 where the use of a Last-Modified value as a validator by an 538 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 539 origin servers should not provide one. 541 2.2.5. Example: Entity-tags varying on Content-Negotiated Resources 543 Consider a resource that is subject to content negotiation (Section 5 544 of [Part3]), and where the representations returned upon a GET 545 request vary based on the Accept-Encoding request header field 546 (Section 6.3 of [Part3]): 548 >> Request: 550 GET /index HTTP/1.1 551 Host: www.example.com 552 Accept-Encoding: gzip 554 In this case, the response might or might not use the gzip content 555 coding. If it does not, the response might look like: 557 >> Response: 559 HTTP/1.1 200 OK 560 Date: Thu, 26 Mar 2010 00:05:00 GMT 561 ETag: "123-a" 562 Content-Length: 70 563 Vary: Accept-Encoding 564 Content-Type: text/plain 566 Hello World! 567 Hello World! 568 Hello World! 569 Hello World! 570 Hello World! 572 An alternative representation that does use gzip content coding would 573 be: 575 >> Response: 577 HTTP/1.1 200 OK 578 Date: Thu, 26 Mar 2010 00:05:00 GMT 579 ETag: "123-b" 580 Content-Length: 43 581 Vary: Accept-Encoding 582 Content-Type: text/plain 583 Content-Encoding: gzip 585 ...binary data... 587 Note: Content codings are a property of the representation, so 588 therefore an entity-tag of an encoded representation must be 589 distinct from an unencoded representation to prevent conflicts 590 during cache updates and range requests. In contrast, transfer 591 codings (Section 6.2 of [Part1]) apply only during message 592 transfer and do not require distinct entity-tags. 594 3. Precondition Header Fields 596 This section defines the syntax and semantics of HTTP/1.1 header 597 fields for applying preconditions on requests. 599 3.1. If-Match 601 The "If-Match" header field MAY be used to make a request method 602 conditional on the current existence or value of an entity-tag for 603 one or more representations of the target resource. If-Match is 604 generally useful for resource update requests, such as PUT requests, 605 as a means for protecting against accidental overwrites when multiple 606 clients are acting in parallel on the same resource (i.e., the "lost 607 update" problem). An If-Match field-value of "*" places the 608 precondition on the existence of any current representation for the 609 target resource. 611 If-Match = "*" / 1#entity-tag 613 If any of the entity-tags listed in the If-Match field value match 614 (as per Section 2.2.3) the entity-tag of the selected representation 615 for the target resource, or if "*" is given and any current 616 representation exists for the target resource, then the server MAY 617 perform the request method as if the If-Match header field was not 618 present. 620 If none of the entity-tags match, or if "*" is given and no current 621 representation exists, the server MUST NOT perform the requested 622 method. Instead, the server MUST respond with the 412 (Precondition 623 Failed) status code. 625 If the request would, without the If-Match header field, result in 626 anything other than a 2xx or 412 status code, then the If-Match 627 header field MUST be ignored. 629 Examples: 631 If-Match: "xyzzy" 632 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 633 If-Match: * 635 The result of a request having both an If-Match header field and 636 either an If-None-Match or an If-Modified-Since header fields is 637 undefined by this specification. 639 3.2. If-None-Match 641 The "If-None-Match" header field MAY be used to make a request method 642 conditional on not matching any of the current entity-tag values for 643 representations of the target resource. If-None-Match is primarily 644 used in conditional GET requests to enable efficient updates of 645 cached information with a minimum amount of transaction overhead. A 646 client that has one or more representations previously obtained from 647 the target resource can send If-None-Match with a list of the 648 associated entity-tags in the hope of receiving a 304 response if at 649 least one of those representations matches the selected 650 representation. 652 If-None-Match MAY also be used with a value of "*" to prevent an 653 unsafe request method (e.g., PUT) from inadvertently modifying an 654 existing representation of the target resource when the client 655 believes that the resource does not have a current representation. 656 This is a variation on the "lost update" problem that might arise if 657 more than one client attempts to create an initial representation for 658 the target resource. 660 If-None-Match = "*" / 1#entity-tag 662 If any of the entity-tags listed in the If-None-Match field-value 663 match (as per Section 2.2.3) the entity-tag of the selected 664 representation, or if "*" is given and any current representation 665 exists for that resource, then the server MUST NOT perform the 666 requested method. Instead, if the request method was GET or HEAD, 667 the server SHOULD respond with a 304 (Not Modified) status code, 668 including the cache-related header fields (particularly ETag) of the 669 selected representation that has a matching entity-tag. For all 670 other request methods, the server MUST respond with a 412 671 (Precondition Failed) status code. 673 If none of the entity-tags match, then the server MAY perform the 674 requested method as if the If-None-Match header field did not exist, 675 but MUST also ignore any If-Modified-Since header field(s) in the 676 request. That is, if no entity-tags match, then the server MUST NOT 677 return a 304 (Not Modified) response. 679 If the request would, without the If-None-Match header field, result 680 in anything other than a 2xx or 304 status code, then the If-None- 681 Match header field MUST be ignored. (See Section 2.2.4 for a 682 discussion of server behavior when both If-Modified-Since and If- 683 None-Match appear in the same request.) 685 Examples: 687 If-None-Match: "xyzzy" 688 If-None-Match: W/"xyzzy" 689 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 690 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 691 If-None-Match: * 693 The result of a request having both an If-None-Match header field and 694 either an If-Match or an If-Unmodified-Since header fields is 695 undefined by this specification. 697 3.3. If-Modified-Since 699 The "If-Modified-Since" header field MAY be used to make a request 700 method conditional by modification date: if the selected 701 representation has not been modified since the time specified in this 702 field, then do not perform the request method; instead, respond as 703 detailed below. 705 If-Modified-Since = HTTP-date 707 An example of the field is: 709 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 711 A GET method with an If-Modified-Since header field and no Range 712 header field requests that the selected representation be transferred 713 only if it has been modified since the date given by the If-Modified- 714 Since header field. The algorithm for determining this includes the 715 following cases: 717 1. If the request would normally result in anything other than a 200 718 (OK) status code, or if the passed If-Modified-Since date is 719 invalid, the response is exactly the same as for a normal GET. A 720 date which is later than the server's current time is invalid. 722 2. If the selected representation has been modified since the If- 723 Modified-Since date, the response is exactly the same as for a 724 normal GET. 726 3. If the selected representation has not been modified since a 727 valid If-Modified-Since date, the server SHOULD return a 304 (Not 728 Modified) response. 730 The purpose of this feature is to allow efficient updates of cached 731 information with a minimum amount of transaction overhead. 733 Note: The Range header field modifies the meaning of If-Modified- 734 Since; see Section 5.4 of [Part5] for full details. 736 Note: If-Modified-Since times are interpreted by the server, whose 737 clock might not be synchronized with the client. 739 Note: When handling an If-Modified-Since header field, some 740 servers will use an exact date comparison function, rather than a 741 less-than function, for deciding whether to send a 304 (Not 742 Modified) response. To get best results when sending an If- 743 Modified-Since header field for cache validation, clients are 744 advised to use the exact date string received in a previous Last- 745 Modified header field whenever possible. 747 Note: If a client uses an arbitrary date in the If-Modified-Since 748 header field instead of a date taken from the Last-Modified header 749 field for the same request, the client needs to be aware that this 750 date is interpreted in the server's understanding of time. 751 Unsynchronized clocks and rounding problems, due to the different 752 encodings of time between the client and server, are concerns. 753 This includes the possibility of race conditions if the document 754 has changed between the time it was first requested and the If- 755 Modified-Since date of a subsequent request, and the possibility 756 of clock-skew-related problems if the If-Modified-Since date is 757 derived from the client's clock without correction to the server's 758 clock. Corrections for different time bases between client and 759 server are at best approximate due to network latency. 761 The result of a request having both an If-Modified-Since header field 762 and either an If-Match or an If-Unmodified-Since header fields is 763 undefined by this specification. 765 3.4. If-Unmodified-Since 767 The "If-Unmodified-Since" header field MAY be used to make a request 768 method conditional by modification date: if the selected 769 representation has been modified since the time specified in this 770 field, then the server MUST NOT perform the requested operation and 771 MUST instead respond with the 412 (Precondition Failed) status code. 772 If the selected representation has not been modified since the time 773 specified in this field, the server SHOULD perform the request method 774 as if the If-Unmodified-Since header field were not present. 776 If-Unmodified-Since = HTTP-date 778 An example of the field is: 780 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 782 If the request normally (i.e., without the If-Unmodified-Since header 783 field) would result in anything other than a 2xx or 412 status code, 784 the If-Unmodified-Since header field SHOULD be ignored. 786 If the specified date is invalid, the header field MUST be ignored. 788 The result of a request having both an If-Unmodified-Since header 789 field and either an If-None-Match or an If-Modified-Since header 790 fields is undefined by this specification. 792 3.5. If-Range 794 The If-Range header field provides a special conditional request 795 mechanism that is similar to If-Match and If-Unmodified-Since but 796 specific to HTTP range requests. If-Range is defined in Section 5.3 797 of [Part5]. 799 4. Status Code Definitions 801 4.1. 304 Not Modified 803 The 304 status code indicates that a conditional GET request has been 804 received and would have resulted in a 200 (OK) response if it were 805 not for the fact that the condition has evaluated to false. In other 806 words, there is no need for the server to transfer a representation 807 of the target resource because the client's request indicates that it 808 already has a valid representation, as indicated by the 304 response 809 header fields, and is therefore redirecting the client to make use of 810 that stored representation as if it were the payload of a 200 811 response. The 304 response MUST NOT contain a message-body, and thus 812 is always terminated by the first empty line after the header fields. 814 A 304 response MUST include a Date header field (Section 9.3 of 815 [Part1]) unless its omission is required by Section 9.3.1 of [Part1]. 816 If a 200 response to the same request would have included any of the 817 header fields Cache-Control, Content-Location, ETag, Expires, Last- 818 Modified, or Vary, then those same header fields MUST be sent in a 819 304 response. 821 Since the goal of a 304 response is to minimize information transfer 822 when the recipient already has one or more cached representations, 823 the response SHOULD NOT include representation metadata other than 824 the above listed fields unless said metadata exists for the purpose 825 of guiding cache updates (e.g., future HTTP extensions). 827 If the recipient of a 304 response does not have a cached 828 representation corresponding to the entity-tag indicated by the 304 829 response, then the recipient MUST NOT use the 304 to update its own 830 cache. If this conditional request originated with an outbound 831 client, such as a user agent with its own cache sending a conditional 832 GET to a shared proxy, then the 304 response MAY be forwarded to the 833 outbound client. Otherwise, the recipient MUST disregard the 304 834 response and repeat the request without any preconditions. 836 If a cache uses a received 304 response to update a cache entry, the 837 cache MUST update the entry to reflect any new field values given in 838 the response. 840 4.2. 412 Precondition Failed 842 The 412 status code indicates that one or more preconditions given in 843 the request header fields evaluated to false when tested on the 844 server. This response code allows the client to place preconditions 845 on the current resource state (its current representations and 846 metadata) and thus prevent the request method from being applied if 847 the target resource is in an unexpected state. 849 5. IANA Considerations 851 5.1. Status Code Registration 853 The HTTP Status Code Registry located at 854 shall be updated 855 with the registrations below: 857 +-------+---------------------+-------------+ 858 | Value | Description | Reference | 859 +-------+---------------------+-------------+ 860 | 304 | Not Modified | Section 4.1 | 861 | 412 | Precondition Failed | Section 4.2 | 862 +-------+---------------------+-------------+ 864 5.2. Header Field Registration 866 The Message Header Field Registry located at shall be 868 updated with the permanent registrations below (see [RFC3864]): 870 +---------------------+----------+----------+-------------+ 871 | Header Field Name | Protocol | Status | Reference | 872 +---------------------+----------+----------+-------------+ 873 | ETag | http | standard | Section 2.2 | 874 | If-Match | http | standard | Section 3.1 | 875 | If-Modified-Since | http | standard | Section 3.3 | 876 | If-None-Match | http | standard | Section 3.2 | 877 | If-Unmodified-Since | http | standard | Section 3.4 | 878 | Last-Modified | http | standard | Section 2.1 | 879 +---------------------+----------+----------+-------------+ 881 The change controller is: "IETF (iesg@ietf.org) - Internet 882 Engineering Task Force". 884 6. Security Considerations 886 No additional security considerations have been identified beyond 887 those applicable to HTTP in general [Part1]. 889 7. Acknowledgments 891 8. References 893 8.1. Normative References 895 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 896 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 897 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 898 and Message Parsing", draft-ietf-httpbis-p1-messaging-15 899 (work in progress), July 2011. 901 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 902 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 903 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 904 and Content Negotiation", draft-ietf-httpbis-p3-payload-15 905 (work in progress), July 2011. 907 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 908 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 909 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 910 Partial Responses", draft-ietf-httpbis-p5-range-15 (work 911 in progress), July 2011. 913 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 914 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 915 Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1, part 916 6: Caching", draft-ietf-httpbis-p6-cache-15 (work in 917 progress), July 2011. 919 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 920 Requirement Levels", BCP 14, RFC 2119, March 1997. 922 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 923 Specifications: ABNF", STD 68, RFC 5234, January 2008. 925 8.2. Informative References 927 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 928 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 929 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 931 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 932 Procedures for Message Header Fields", BCP 90, RFC 3864, 933 September 2004. 935 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 936 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 938 Appendix A. Changes from RFC 2616 940 Allow weak entity-tags in all requests except range requests 941 (Sections 2.2.2 and 3.2). 943 Change ABNF productions for header fields to only define the field 944 value. (Section 3) 946 Appendix B. Collected ABNF 948 ETag = entity-tag 950 HTTP-date = 952 If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 953 entity-tag ] ) ) 954 If-Modified-Since = HTTP-date 955 If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 956 entity-tag ] ) ) 957 If-Unmodified-Since = HTTP-date 959 Last-Modified = HTTP-date 961 OWS = 963 entity-tag = [ weak ] opaque-tag 965 opaque-tag = quoted-string 967 quoted-string = 969 weak = %x57.2F ; W/ 971 ABNF diagnostics: 973 ; ETag defined but not used 974 ; If-Match defined but not used 975 ; If-Modified-Since defined but not used 976 ; If-None-Match defined but not used 977 ; If-Unmodified-Since defined but not used 978 ; Last-Modified defined but not used 980 Appendix C. Change Log (to be removed by RFC Editor before publication) 982 C.1. Since RFC 2616 984 Extracted relevant partitions from [RFC2616]. 986 C.2. Since draft-ietf-httpbis-p4-conditional-00 988 Closed issues: 990 o : "Normative and 991 Informative references" 993 Other changes: 995 o Move definitions of 304 and 412 condition codes from Part2. 997 C.3. Since draft-ietf-httpbis-p4-conditional-01 999 Ongoing work on ABNF conversion 1000 (): 1002 o Add explicit references to BNF syntax and rules imported from 1003 other parts of the specification. 1005 C.4. Since draft-ietf-httpbis-p4-conditional-02 1007 Closed issues: 1009 o : "Weak ETags on 1010 non-GET requests" 1012 Ongoing work on IANA Message Header Field Registration 1013 (): 1015 o Reference RFC 3984, and update header field registrations for 1016 header fields defined in this document. 1018 C.5. Since draft-ietf-httpbis-p4-conditional-03 1020 Closed issues: 1022 o : "Examples for 1023 ETag matching" 1025 o : "'entity 1026 value' undefined" 1028 o : "bogus 2068 1029 Date header reference" 1031 C.6. Since draft-ietf-httpbis-p4-conditional-04 1033 Ongoing work on ABNF conversion 1034 (): 1036 o Use "/" instead of "|" for alternatives. 1038 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1039 whitespace ("OWS") and required whitespace ("RWS"). 1041 o Rewrite ABNFs to spell out whitespace rules, factor out header 1042 field value format definitions. 1044 C.7. Since draft-ietf-httpbis-p4-conditional-05 1046 Final work on ABNF conversion 1047 (): 1049 o Add appendix containing collected and expanded ABNF, reorganize 1050 ABNF introduction. 1052 C.8. Since draft-ietf-httpbis-p4-conditional-06 1054 Closed issues: 1056 o : "case- 1057 sensitivity of etag weakness indicator" 1059 C.9. Since draft-ietf-httpbis-p4-conditional-07 1061 Closed issues: 1063 o : "Weak ETags on 1064 non-GET requests" (If-Match still was defined to require strong 1065 matching) 1067 o : "move IANA 1068 registrations for optional status codes" 1070 C.10. Since draft-ietf-httpbis-p4-conditional-08 1072 No significant changes. 1074 C.11. Since draft-ietf-httpbis-p4-conditional-09 1076 No significant changes. 1078 C.12. Since draft-ietf-httpbis-p4-conditional-10 1080 Closed issues: 1082 o : "Clarify 1083 'Requested Variant'" 1085 o : "Clarify 1086 entity / representation / variant terminology" 1088 o : "consider 1089 removing the 'changes from 2068' sections" 1091 C.13. Since draft-ietf-httpbis-p4-conditional-11 1093 None. 1095 C.14. Since draft-ietf-httpbis-p4-conditional-12 1097 Closed issues: 1099 o : "Header 1100 Classification" 1102 C.15. Since draft-ietf-httpbis-p4-conditional-13 1104 Closed issues: 1106 o : "If-* and 1107 entities" 1109 o : "Definition of 1110 validator weakness" 1112 o : "untangle 1113 ABNFs for header fields" 1115 o : "ETags and 1116 Quotes" 1118 C.16. Since draft-ietf-httpbis-p4-conditional-14 1120 None. 1122 Index 1124 3 1125 304 Not Modified (status code) 18 1127 4 1128 412 Precondition Failed (status code) 19 1130 E 1131 ETag header field 8 1133 G 1134 Grammar 1135 entity-tag 8 1136 ETag 8 1137 If-Match 14 1138 If-Modified-Since 16 1139 If-None-Match 15 1140 If-Unmodified-Since 18 1141 Last-Modified 6 1142 opaque-tag 8 1143 weak 8 1145 H 1146 Header Fields 1147 ETag 8 1148 If-Match 14 1149 If-Modified-Since 16 1150 If-None-Match 15 1151 If-Unmodified-Since 18 1152 Last-Modified 6 1154 I 1155 If-Match header field 14 1156 If-Modified-Since header field 16 1157 If-None-Match header field 15 1158 If-Unmodified-Since header field 18 1160 L 1161 Last-Modified header field 6 1163 M 1164 metadata 6 1166 S 1167 selected representation 5 1168 Status Codes 1169 304 Not Modified 18 1170 412 Precondition Failed 19 1172 V 1173 validator 6 1175 Authors' Addresses 1177 Roy T. Fielding (editor) 1178 Adobe Systems Incorporated 1179 345 Park Ave 1180 San Jose, CA 95110 1181 USA 1183 EMail: fielding@gbiv.com 1184 URI: http://roy.gbiv.com/ 1185 Jim Gettys 1186 Alcatel-Lucent Bell Labs 1187 21 Oak Knoll Road 1188 Carlisle, MA 01741 1189 USA 1191 EMail: jg@freedesktop.org 1192 URI: http://gettys.wordpress.com/ 1194 Jeffrey C. Mogul 1195 Hewlett-Packard Company 1196 HP Labs, Large Scale Systems Group 1197 1501 Page Mill Road, MS 1177 1198 Palo Alto, CA 94304 1199 USA 1201 EMail: JeffMogul@acm.org 1203 Henrik Frystyk Nielsen 1204 Microsoft Corporation 1205 1 Microsoft Way 1206 Redmond, WA 98052 1207 USA 1209 EMail: henrikn@microsoft.com 1211 Larry Masinter 1212 Adobe Systems Incorporated 1213 345 Park Ave 1214 San Jose, CA 95110 1215 USA 1217 EMail: LMM@acm.org 1218 URI: http://larry.masinter.net/ 1220 Paul J. Leach 1221 Microsoft Corporation 1222 1 Microsoft Way 1223 Redmond, WA 98052 1225 EMail: paulle@microsoft.com 1226 Tim Berners-Lee 1227 World Wide Web Consortium 1228 MIT Computer Science and Artificial Intelligence Laboratory 1229 The Stata Center, Building 32 1230 32 Vassar Street 1231 Cambridge, MA 02139 1232 USA 1234 EMail: timbl@w3.org 1235 URI: http://www.w3.org/People/Berners-Lee/ 1237 Yves Lafon (editor) 1238 World Wide Web Consortium 1239 W3C / ERCIM 1240 2004, rte des Lucioles 1241 Sophia-Antipolis, AM 06902 1242 France 1244 EMail: ylafon@w3.org 1245 URI: http://www.raubacapeu.net/people/yves/ 1247 Julian F. Reschke (editor) 1248 greenbytes GmbH 1249 Hafenweg 16 1250 Muenster, NW 48155 1251 Germany 1253 Phone: +49 251 2807760 1254 Fax: +49 251 2807761 1255 EMail: julian.reschke@greenbytes.de 1256 URI: http://greenbytes.de/tech/webdav/