idnits 2.17.1 draft-ietf-httpbis-p4-conditional-14.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 (April 18, 2011) is 4756 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-14 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-14 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-14 -- 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: October 20, 2011 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 April 18, 2011 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-14 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.15. 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 October 20, 2011. 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 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 148 1. Introduction 150 This document defines the HTTP/1.1 conditional request mechanisms, 151 including both response metadata that can be used to indicate or 152 observe changes to resource state and request header fields that 153 specify preconditions to be checked before performing the action 154 given by the request method. Conditional GET requests are the most 155 efficient mechanism for HTTP cache updates [Part6]. Conditionals can 156 also be applied to state-changing methods, such as PUT and DELETE, to 157 prevent the "lost update" problem: one client accidentally 158 overwriting the work of another client that has been acting in 159 parallel. 161 Conditional request preconditions are based on the state of the 162 target resource as a whole (its current value set) or the state as 163 observed in a previously obtained representation (one value in that 164 set). A resource might have multiple current representations, each 165 with its own observable state. The conditional request mechanisms 166 assume that the mapping of requests to corresponding representations 167 will be consistent over time if the server intends to take advantage 168 of conditionals. Regardless, if the mapping is inconsistent and the 169 server is unable to select the appropriate representation, then no 170 harm will result when the precondition evaluates to false. 172 We use the term "selected representation" to refer to the current 173 representation of the target resource that would have been selected 174 in a successful response if the same request had used the method GET 175 and had excluded all of the conditional request header fields. The 176 conditional request preconditions are evaluated by comparing the 177 values provided in the request header fields to the current metadata 178 for the selected representation. 180 1.1. Requirements 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 184 document are to be interpreted as described in [RFC2119]. 186 An implementation is not compliant if it fails to satisfy one or more 187 of the "MUST" or "REQUIRED" level requirements for the protocols it 188 implements. An implementation that satisfies all the "MUST" or 189 "REQUIRED" level and all the "SHOULD" level requirements for its 190 protocols is said to be "unconditionally compliant"; one that 191 satisfies all the "MUST" level requirements but not all the "SHOULD" 192 level requirements for its protocols is said to be "conditionally 193 compliant". 195 1.2. Syntax Notation 197 This specification uses the ABNF syntax defined in Section 1.2 of 198 [Part1] (which extends the syntax defined in [RFC5234] with a list 199 rule). Appendix B shows the collected ABNF, with the list rule 200 expanded. 202 The following core rules are included by reference, as defined in 203 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF 204 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), 205 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 206 sequence of data), SP (space), VCHAR (any visible USASCII character), 207 and WSP (whitespace). 209 The ABNF rules below are defined in other parts: 211 quoted-string = 212 OWS = 213 HTTP-date = 215 2. Resource State Metadata (Validators) 217 This specification defines two forms of metadata that are commonly 218 used to observe resource state and test for preconditions: 219 modification dates and opaque entity tags. Additional metadata that 220 reflects resource state has been defined by various extensions of 221 HTTP, such as WebDAV [RFC4918], that are beyond the scope of this 222 specification. A resource metadata value is referred to as a 223 "validator" when it is used within a precondition. 225 2.1. Last-Modified 227 The "Last-Modified" header field indicates the date and time at which 228 the origin server believes the selected representation was last 229 modified. 231 Last-Modified = HTTP-date 233 An example of its use is 235 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 237 2.1.1. Generation 239 Origin servers SHOULD send Last-Modified for any selected 240 representation for which a last modification date can be reasonably 241 and consistently determined, since its use in conditional requests 242 and evaluating cache freshness ([Part6]) results in a substantial 243 reduction of HTTP traffic on the Internet and can be a significant 244 factor in improving service scalability and reliability. 246 A representation is typically the sum of many parts behind the 247 resource interface. The last-modified time would usually be the most 248 recent time that any of those parts were changed. How that value is 249 determined for any given resource is an implementation detail beyond 250 the scope of this specification. What matters to HTTP is how 251 recipients of the Last-Modified header field can use its value to 252 make conditional requests and test the validity of locally cached 253 responses. 255 An origin server SHOULD obtain the Last-Modified value of the 256 representation as close as possible to the time that it generates the 257 Date field-value for its response. This allows a recipient to make 258 an accurate assessment of the representation's modification time, 259 especially if the representation changes near the time that the 260 response is generated. 262 An origin server with a clock MUST NOT send a Last-Modified date that 263 is later than the server's time of message origination (Date). If 264 the last modification time is derived from implementation-specific 265 metadata that evaluates to some time in the future, according to the 266 origin server's clock, then the origin server MUST replace that value 267 with the message origination date. This prevents a future 268 modification date from having an adverse impact on cache validation. 270 2.1.2. Comparison 272 A Last-Modified time, when used as a validator in a request, is 273 implicitly weak unless it is possible to deduce that it is strong, 274 using the following rules: 276 o The validator is being compared by an origin server to the actual 277 current validator for the representation and, 279 o That origin server reliably knows that the associated 280 representation did not change twice during the second covered by 281 the presented validator. 283 or 285 o The validator is about to be used by a client in an If-Modified- 286 Since or If-Unmodified-Since header field, because the client has 287 a cache entry for the associated representation, and 289 o That cache entry includes a Date value, which gives the time when 290 the origin server sent the original response, and 292 o The presented Last-Modified time is at least 60 seconds before the 293 Date value. 295 or 297 o The validator is being compared by an intermediate cache to the 298 validator stored in its cache entry for the representation, and 300 o That cache entry includes a Date value, which gives the time when 301 the origin server sent the original response, and 303 o The presented Last-Modified time is at least 60 seconds before the 304 Date value. 306 This method relies on the fact that if two different responses were 307 sent by the origin server during the same second, but both had the 308 same Last-Modified time, then at least one of those responses would 309 have a Date value equal to its Last-Modified time. The arbitrary 60- 310 second limit guards against the possibility that the Date and Last- 311 Modified values are generated from different clocks, or at somewhat 312 different times during the preparation of the response. An 313 implementation MAY use a value larger than 60 seconds, if it is 314 believed that 60 seconds is too short. 316 2.2. ETag 318 The ETag header field provides the current entity-tag for the 319 selected representation. An entity-tag is an opaque validator for 320 differentiating between multiple representations of the same 321 resource, regardless of whether those multiple representations are 322 due to resource state changes over time, content negotiation 323 resulting in multiple representations being valid at the same time, 324 or both. An entity-tag consists of an opaque quoted string, possibly 325 prefixed by a weakness indicator. 327 ETag = entity-tag 329 entity-tag = [ weak ] opaque-tag 330 weak = %x57.2F ; "W/", case-sensitive 331 opaque-tag = quoted-string 333 An entity-tag can be more reliable for validation than a modification 334 date in situations where it is inconvenient to store modification 335 dates, where the one-second resolution of HTTP date values is not 336 sufficient, or where modification dates are not consistently 337 maintained. 339 Examples: 341 ETag: "xyzzy" 342 ETag: W/"xyzzy" 343 ETag: "" 345 2.2.1. Generation 347 The principle behind entity-tags is that only the service author 348 knows the implementation of a resource well enough to select the most 349 accurate and efficient validation mechanism for that resource, and 350 that any such mechanism can be mapped to a simple sequence of octets 351 for easy comparison. Since the value is opaque, there is no need for 352 the client to be aware of how each entity-tag is constructed. 354 For example, a resource that has implementation-specific versioning 355 applied to all changes might use an internal revision number, perhaps 356 combined with a variance identifier for content negotiation, to 357 accurately differentiate between representations. Other 358 implementations might use a stored hash of representation content, a 359 combination of various filesystem attributes, or a modification 360 timestamp that has sub-second resolution. 362 Origin servers SHOULD send ETag for any selected representation for 363 which detection of changes can be reasonably and consistently 364 determined, since the entity-tag's use in conditional requests and 365 evaluating cache freshness ([Part6]) can result in a substantial 366 reduction of HTTP network traffic and can be a significant factor in 367 improving service scalability and reliability. 369 2.2.2. Weak versus Strong 371 Since both origin servers and caches will compare two validators to 372 decide if they indicate the same or different representations, one 373 normally would expect that if the representation (including both 374 representation header fields and representation body) changes in any 375 way, then the associated validator would change as well. If this is 376 true, then we call that validator a "strong validator". One example 377 of a strong validator is an integer that is incremented in stable 378 storage every time a representation is changed. 380 However, there might be cases when a server prefers to change the 381 validator only when it desires cached representations to be 382 invalidated. For example, the representation of a weather report 383 that changes in content every second, based on dynamic measurements, 384 might be grouped into sets of equivalent representations (from the 385 origin server's perspective) in order to allow cached representations 386 to be valid for a reasonable period of time (perhaps adjusted 387 dynamically based on server load or weather quality). A validator 388 that does not always change when the representation changes is a 389 "weak validator". 391 One can think of a strong validator as part of an identifier for a 392 specific representation, whereas a weak validator is part of an 393 identifier for a set of equivalent representations (where this notion 394 of equivalence is entirely governed by the origin server and beyond 395 the scope of this specification). 397 An entity-tag is normally a strong validator, but the protocol 398 provides a mechanism to tag an entity-tag as "weak". 400 A representation's modification time, if defined with only one- 401 second resolution, could be a weak validator, since it is possible 402 that the representation might be modified twice during a single 403 second. 405 Support for weak validators is optional. However, weak validators 406 allow for more efficient caching of equivalent objects; for 407 example, a hit counter on a site is probably good enough if it is 408 updated every few days or weeks, and any value during that period 409 is likely "good enough" to be equivalent. 411 A strong entity-tag MUST change whenever the associated 412 representation changes in any way. A weak entity-tag SHOULD change 413 whenever the origin server considers prior representations to be 414 unacceptable as a substitute for the current representation. In 415 other words, a weak entity tag SHOULD change whenever the origin 416 server wants caches to invalidate old responses. 418 A "strong entity-tag" MAY be shared by two representations of a 419 resource only if they are equivalent by octet equality. 421 A "weak entity-tag", indicated by the "W/" prefix, MAY be shared by 422 two representations of a resource. A weak entity-tag can only be 423 used for weak comparison. 425 Cache entries might persist for arbitrarily long periods, regardless 426 of expiration times. Thus, a cache might attempt to validate an 427 entry using a validator that it obtained in the distant past. A 428 strong entity-tag MUST be unique across all versions of all 429 representations associated with a particular resource over time. 430 However, there is no implication of uniqueness across entity-tags of 431 different resources (i.e., the same entity-tag value might be in use 432 for representations of multiple resources at the same time and does 433 not imply that those representations are equivalent). 435 2.2.3. Comparison 437 There are two entity-tag comparison functions, depending on whether 438 the comparison context allows the use of weak validators or not: 440 o The strong comparison function: in order to be considered equal, 441 both opaque-tags MUST be identical character-by-character, and 442 both MUST NOT be weak. 444 o The weak comparison function: in order to be considered equal, 445 both opaque-tags MUST be identical character-by-character, but 446 either or both of them MAY be tagged as "weak" without affecting 447 the result. 449 A "use" of a validator is either when a client generates a request 450 and includes the validator in a precondition, or when a server 451 compares two validators. 453 Strong validators are usable in any context. Weak validators are 454 only usable in contexts that do not depend on exact equality of a 455 representation. For example, either kind is usable for a normal 456 conditional GET. 458 The example below shows the results for a set of entity-tag pairs, 459 and both the weak and strong comparison function results: 461 +--------+--------+-------------------+-----------------+ 462 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 463 +--------+--------+-------------------+-----------------+ 464 | W/"1" | W/"1" | no match | match | 465 | W/"1" | W/"2" | no match | no match | 466 | W/"1" | "1" | no match | match | 467 | "1" | "1" | match | match | 468 +--------+--------+-------------------+-----------------+ 470 An entity-tag is strong unless it is explicitly tagged as weak. 472 2.2.4. Rules for When to Use Entity-tags and Last-Modified Dates 474 We adopt a set of rules and recommendations for origin servers, 475 clients, and caches regarding when various validator types ought to 476 be used, and for what purposes. 478 HTTP/1.1 origin servers: 480 o SHOULD send an entity-tag validator unless it is not feasible to 481 generate one. 483 o MAY send a weak entity-tag instead of a strong entity-tag, if 484 performance considerations support the use of weak entity-tags, or 485 if it is unfeasible to send a strong entity-tag. 487 o SHOULD send a Last-Modified value if it is feasible to send one. 489 In other words, the preferred behavior for an HTTP/1.1 origin server 490 is to send both a strong entity-tag and a Last-Modified value. 492 HTTP/1.1 clients: 494 o MUST use that entity-tag in any cache-conditional request (using 495 If-Match or If-None-Match) if an entity-tag has been provided by 496 the origin server. 498 o SHOULD use the Last-Modified value in non-subrange cache- 499 conditional requests (using If-Modified-Since) if only a Last- 500 Modified value has been provided by the origin server. 502 o MAY use the Last-Modified value in subrange cache-conditional 503 requests (using If-Unmodified-Since) if only a Last-Modified value 504 has been provided by an HTTP/1.0 origin server. The user agent 505 SHOULD provide a way to disable this, in case of difficulty. 507 o SHOULD use both validators in cache-conditional requests if both 508 an entity-tag and a Last-Modified value have been provided by the 509 origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to 510 respond appropriately. 512 An HTTP/1.1 origin server, upon receiving a conditional request that 513 includes both a Last-Modified date (e.g., in an If-Modified-Since or 514 If-Unmodified-Since header field) and one or more entity-tags (e.g., 515 in an If-Match, If-None-Match, or If-Range header field) as cache 516 validators, MUST NOT return a response status code of 304 (Not 517 Modified) unless doing so is consistent with all of the conditional 518 header fields in the request. 520 An HTTP/1.1 caching proxy, upon receiving a conditional request that 521 includes both a Last-Modified date and one or more entity-tags as 522 cache validators, MUST NOT return a locally cached response to the 523 client unless that cached response is consistent with all of the 524 conditional header fields in the request. 526 Note: The general principle behind these rules is that HTTP/1.1 527 servers and clients ought to transmit as much non-redundant 528 information as is available in their responses and requests. 529 HTTP/1.1 systems receiving this information will make the most 530 conservative assumptions about the validators they receive. 532 HTTP/1.0 clients and caches might ignore entity-tags. Generally, 533 last-modified values received or used by these systems will 534 support transparent and efficient caching, and so HTTP/1.1 origin 535 servers should provide Last-Modified values. In those rare cases 536 where the use of a Last-Modified value as a validator by an 537 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 538 origin servers should not provide one. 540 2.2.5. Example: Entity-tags varying on Content-Negotiated Resources 542 Consider a resource that is subject to content negotiation (Section 5 543 of [Part3]), and where the representations returned upon a GET 544 request vary based on the Accept-Encoding request header field 545 (Section 6.3 of [Part3]): 547 >> Request: 549 GET /index HTTP/1.1 550 Host: www.example.com 551 Accept-Encoding: gzip 553 In this case, the response might or might not use the gzip content 554 coding. If it does not, the response might look like: 556 >> Response: 558 HTTP/1.1 200 OK 559 Date: Thu, 26 Mar 2010 00:05:00 GMT 560 ETag: "123-a" 561 Content-Length: 70 562 Vary: Accept-Encoding 563 Content-Type: text/plain 565 Hello World! 566 Hello World! 567 Hello World! 568 Hello World! 569 Hello World! 571 An alternative representation that does use gzip content coding would 572 be: 574 >> Response: 576 HTTP/1.1 200 OK 577 Date: Thu, 26 Mar 2010 00:05:00 GMT 578 ETag: "123-b" 579 Content-Length: 43 580 Vary: Accept-Encoding 581 Content-Type: text/plain 582 Content-Encoding: gzip 584 ...binary data... 586 Note: Content codings are a property of the representation, so 587 therefore an entity-tag of an encoded representation must be 588 distinct from an unencoded representation to prevent conflicts 589 during cache updates and range requests. In contrast, transfer 590 codings (Section 6.2 of [Part1]) apply only during message 591 transfer and do not require distinct entity-tags. 593 3. Precondition Header Fields 595 This section defines the syntax and semantics of HTTP/1.1 header 596 fields for applying preconditions on requests. 598 3.1. If-Match 600 The "If-Match" header field MAY be used to make a request method 601 conditional on the current existence or value of an entity-tag for 602 one or more representations of the target resource. If-Match is 603 generally useful for resource update requests, such as PUT requests, 604 as a means for protecting against accidental overwrites when multiple 605 clients are acting in parallel on the same resource (i.e., the "lost 606 update" problem). An If-Match field-value of "*" places the 607 precondition on the existence of any current representation for the 608 target resource. 610 If-Match = "*" / 1#entity-tag 612 If any of the entity-tags listed in the If-Match field value match 613 (as per Section 2.2.3) the entity-tag of the selected representation 614 for the target resource, or if "*" is given and any current 615 representation exists for the target resource, then the server MAY 616 perform the request method as if the If-Match header field was not 617 present. 619 If none of the entity-tags match, or if "*" is given and no current 620 representation exists, the server MUST NOT perform the requested 621 method. Instead, the server MUST respond with the 412 (Precondition 622 Failed) status code. 624 If the request would, without the If-Match header field, result in 625 anything other than a 2xx or 412 status code, then the If-Match 626 header field MUST be ignored. 628 Examples: 630 If-Match: "xyzzy" 631 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 632 If-Match: * 634 The result of a request having both an If-Match header field and 635 either an If-None-Match or an If-Modified-Since header fields is 636 undefined by this specification. 638 3.2. If-None-Match 640 The "If-None-Match" header field MAY be used to make a request method 641 conditional on not matching any of the current entity-tag values for 642 representations of the target resource. If-None-Match is primarily 643 used in conditional GET requests to enable efficient updates of 644 cached information with a minimum amount of transaction overhead. A 645 client that has one or more representations previously obtained from 646 the target resource can send If-None-Match with a list of the 647 associated entity-tags in the hope of receiving a 304 response if at 648 least one of those representations matches the selected 649 representation. 651 If-None-Match MAY also be used with a value of "*" to prevent an 652 unsafe request method (e.g., PUT) from inadvertently modifying an 653 existing representation of the target resource when the client 654 believes that the resource does not have a current representation. 655 This is a variation on the "lost update" problem that might arise if 656 more than one client attempts to create an initial representation for 657 the target resource. 659 If-None-Match = "*" / 1#entity-tag 661 If any of the entity-tags listed in the If-None-Match field-value 662 match (as per Section 2.2.3) the entity-tag of the selected 663 representation, or if "*" is given and any current representation 664 exists for that resource, then the server MUST NOT perform the 665 requested method. Instead, if the request method was GET or HEAD, 666 the server SHOULD respond with a 304 (Not Modified) status code, 667 including the cache-related header fields (particularly ETag) of the 668 selected representation that has a matching entity-tag. For all 669 other request methods, the server MUST respond with a 412 670 (Precondition Failed) status code. 672 If none of the entity-tags match, then the server MAY perform the 673 requested method as if the If-None-Match header field did not exist, 674 but MUST also ignore any If-Modified-Since header field(s) in the 675 request. That is, if no entity-tags match, then the server MUST NOT 676 return a 304 (Not Modified) response. 678 If the request would, without the If-None-Match header field, result 679 in anything other than a 2xx or 304 status code, then the If-None- 680 Match header field MUST be ignored. (See Section 2.2.4 for a 681 discussion of server behavior when both If-Modified-Since and If- 682 None-Match appear in the same request.) 684 Examples: 686 If-None-Match: "xyzzy" 687 If-None-Match: W/"xyzzy" 688 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 689 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 690 If-None-Match: * 692 The result of a request having both an If-None-Match header field and 693 either an If-Match or an If-Unmodified-Since header fields is 694 undefined by this specification. 696 3.3. If-Modified-Since 698 The "If-Modified-Since" header field MAY be used to make a request 699 method conditional by modification date: if the selected 700 representation has not been modified since the time specified in this 701 field, then do not perform the request method; instead, respond as 702 detailed below. 704 If-Modified-Since = HTTP-date 706 An example of the field is: 708 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 710 A GET method with an If-Modified-Since header field and no Range 711 header field requests that the selected representation be transferred 712 only if it has been modified since the date given by the If-Modified- 713 Since header field. The algorithm for determining this includes the 714 following cases: 716 1. If the request would normally result in anything other than a 200 717 (OK) status code, or if the passed If-Modified-Since date is 718 invalid, the response is exactly the same as for a normal GET. A 719 date which is later than the server's current time is invalid. 721 2. If the selected representation has been modified since the If- 722 Modified-Since date, the response is exactly the same as for a 723 normal GET. 725 3. If the selected representation has not been modified since a 726 valid If-Modified-Since date, the server SHOULD return a 304 (Not 727 Modified) response. 729 The purpose of this feature is to allow efficient updates of cached 730 information with a minimum amount of transaction overhead. 732 Note: The Range header field modifies the meaning of If-Modified- 733 Since; see Section 5.4 of [Part5] for full details. 735 Note: If-Modified-Since times are interpreted by the server, whose 736 clock might not be synchronized with the client. 738 Note: When handling an If-Modified-Since header field, some 739 servers will use an exact date comparison function, rather than a 740 less-than function, for deciding whether to send a 304 (Not 741 Modified) response. To get best results when sending an If- 742 Modified-Since header field for cache validation, clients are 743 advised to use the exact date string received in a previous Last- 744 Modified header field whenever possible. 746 Note: If a client uses an arbitrary date in the If-Modified-Since 747 header field instead of a date taken from the Last-Modified header 748 field for the same request, the client needs to be aware that this 749 date is interpreted in the server's understanding of time. 750 Unsynchronized clocks and rounding problems, due to the different 751 encodings of time between the client and server, are concerns. 752 This includes the possibility of race conditions if the document 753 has changed between the time it was first requested and the If- 754 Modified-Since date of a subsequent request, and the possibility 755 of clock-skew-related problems if the If-Modified-Since date is 756 derived from the client's clock without correction to the server's 757 clock. Corrections for different time bases between client and 758 server are at best approximate due to network latency. 760 The result of a request having both an If-Modified-Since header field 761 and either an If-Match or an If-Unmodified-Since header fields is 762 undefined by this specification. 764 3.4. If-Unmodified-Since 766 The "If-Unmodified-Since" header field MAY be used to make a request 767 method conditional by modification date: if the selected 768 representation has been modified since the time specified in this 769 field, then the server MUST NOT perform the requested operation and 770 MUST instead respond with the 412 (Precondition Failed) status code. 771 If the selected representation has not been modified since the time 772 specified in this field, the server SHOULD perform the request method 773 as if the If-Unmodified-Since header field were not present. 775 If-Unmodified-Since = HTTP-date 777 An example of the field is: 779 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 781 If the request normally (i.e., without the If-Unmodified-Since header 782 field) would result in anything other than a 2xx or 412 status code, 783 the If-Unmodified-Since header field SHOULD be ignored. 785 If the specified date is invalid, the header field MUST be ignored. 787 The result of a request having both an If-Unmodified-Since header 788 field and either an If-None-Match or an If-Modified-Since header 789 fields is undefined by this specification. 791 3.5. If-Range 793 The If-Range header field provides a special conditional request 794 mechanism that is similar to If-Match and If-Unmodified-Since but 795 specific to HTTP range requests. If-Range is defined in Section 5.3 796 of [Part5]. 798 4. Status Code Definitions 800 4.1. 304 Not Modified 802 The 304 status code indicates that a conditional GET request has been 803 received and would have resulted in a 200 (OK) response if it were 804 not for the fact that the condition has evaluated to false. In other 805 words, there is no need for the server to transfer a representation 806 of the target resource because the client's request indicates that it 807 already has a valid representation, as indicated by the 304 response 808 header fields, and is therefore redirecting the client to make use of 809 that stored representation as if it were the payload of a 200 810 response. The 304 response MUST NOT contain a message-body, and thus 811 is always terminated by the first empty line after the header fields. 813 A 304 response MUST include a Date header field (Section 9.3 of 814 [Part1]) unless its omission is required by Section 9.3.1 of [Part1]. 815 If a 200 response to the same request would have included any of the 816 header fields Cache-Control, Content-Location, ETag, Expires, Last- 817 Modified, or Vary, then those same header fields MUST be sent in a 818 304 response. 820 Since the goal of a 304 response is to minimize information transfer 821 when the recipient already has one or more cached representations, 822 the response SHOULD NOT include representation metadata other than 823 the above listed fields unless said metadata exists for the purpose 824 of guiding cache updates (e.g., future HTTP extensions). 826 If the recipient of a 304 response does not have a cached 827 representation corresponding to the entity-tag indicated by the 304 828 response, then the recipient MUST NOT use the 304 to update its own 829 cache. If this conditional request originated with an outbound 830 client, such as a user agent with its own cache sending a conditional 831 GET to a shared proxy, then the 304 response MAY be forwarded to the 832 outbound client. Otherwise, the recipient MUST disregard the 304 833 response and repeat the request without any preconditions. 835 If a cache uses a received 304 response to update a cache entry, the 836 cache MUST update the entry to reflect any new field values given in 837 the response. 839 4.2. 412 Precondition Failed 841 The 412 status code indicates that one or more preconditions given in 842 the request header fields evaluated to false when tested on the 843 server. This response code allows the client to place preconditions 844 on the current resource state (its current representations and 845 metadata) and thus prevent the request method from being applied if 846 the target resource is in an unexpected state. 848 5. IANA Considerations 850 5.1. Status Code Registration 852 The HTTP Status Code Registry located at 853 shall be updated 854 with the registrations below: 856 +-------+---------------------+-------------+ 857 | Value | Description | Reference | 858 +-------+---------------------+-------------+ 859 | 304 | Not Modified | Section 4.1 | 860 | 412 | Precondition Failed | Section 4.2 | 861 +-------+---------------------+-------------+ 863 5.2. Header Field Registration 865 The Message Header Field Registry located at shall be 867 updated with the permanent registrations below (see [RFC3864]): 869 +---------------------+----------+----------+-------------+ 870 | Header Field Name | Protocol | Status | Reference | 871 +---------------------+----------+----------+-------------+ 872 | ETag | http | standard | Section 2.2 | 873 | If-Match | http | standard | Section 3.1 | 874 | If-Modified-Since | http | standard | Section 3.3 | 875 | If-None-Match | http | standard | Section 3.2 | 876 | If-Unmodified-Since | http | standard | Section 3.4 | 877 | Last-Modified | http | standard | Section 2.1 | 878 +---------------------+----------+----------+-------------+ 880 The change controller is: "IETF (iesg@ietf.org) - Internet 881 Engineering Task Force". 883 6. Security Considerations 885 No additional security considerations have been identified beyond 886 those applicable to HTTP in general [Part1]. 888 7. Acknowledgments 890 8. References 892 8.1. Normative References 894 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 895 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 896 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 897 and Message Parsing", draft-ietf-httpbis-p1-messaging-14 898 (work in progress), April 2011. 900 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 901 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 902 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 903 and Content Negotiation", draft-ietf-httpbis-p3-payload-14 904 (work in progress), April 2011. 906 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 907 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 908 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 909 Partial Responses", draft-ietf-httpbis-p5-range-14 (work 910 in progress), April 2011. 912 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 913 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 914 Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1, part 915 6: Caching", draft-ietf-httpbis-p6-cache-14 (work in 916 progress), April 2011. 918 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 919 Requirement Levels", BCP 14, RFC 2119, March 1997. 921 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 922 Specifications: ABNF", STD 68, RFC 5234, January 2008. 924 8.2. Informative References 926 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 927 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 928 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 930 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 931 Procedures for Message Header Fields", BCP 90, RFC 3864, 932 September 2004. 934 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 935 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 937 Appendix A. Changes from RFC 2616 939 Allow weak entity-tags in all requests except range requests 940 (Sections 2.2.2 and 3.2). 942 Change ABNF productions for header fields to only define the field 943 value. (Section 3) 945 Appendix B. Collected ABNF 947 ETag = entity-tag 949 HTTP-date = 951 If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 952 entity-tag ] ) ) 953 If-Modified-Since = HTTP-date 954 If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS 955 entity-tag ] ) ) 956 If-Unmodified-Since = HTTP-date 958 Last-Modified = HTTP-date 960 OWS = 962 entity-tag = [ weak ] opaque-tag 964 opaque-tag = quoted-string 966 quoted-string = 968 weak = %x57.2F ; W/ 970 ABNF diagnostics: 972 ; ETag defined but not used 973 ; If-Match defined but not used 974 ; If-Modified-Since defined but not used 975 ; If-None-Match defined but not used 976 ; If-Unmodified-Since defined but not used 977 ; Last-Modified defined but not used 979 Appendix C. Change Log (to be removed by RFC Editor before publication) 981 C.1. Since RFC 2616 983 Extracted relevant partitions from [RFC2616]. 985 C.2. Since draft-ietf-httpbis-p4-conditional-00 987 Closed issues: 989 o : "Normative and 990 Informative references" 992 Other changes: 994 o Move definitions of 304 and 412 condition codes from Part2. 996 C.3. Since draft-ietf-httpbis-p4-conditional-01 998 Ongoing work on ABNF conversion 999 (): 1001 o Add explicit references to BNF syntax and rules imported from 1002 other parts of the specification. 1004 C.4. Since draft-ietf-httpbis-p4-conditional-02 1006 Closed issues: 1008 o : "Weak ETags on 1009 non-GET requests" 1011 Ongoing work on IANA Message Header Field Registration 1012 (): 1014 o Reference RFC 3984, and update header field registrations for 1015 header fields defined in this document. 1017 C.5. Since draft-ietf-httpbis-p4-conditional-03 1019 Closed issues: 1021 o : "Examples for 1022 ETag matching" 1024 o : "'entity 1025 value' undefined" 1027 o : "bogus 2068 1028 Date header reference" 1030 C.6. Since draft-ietf-httpbis-p4-conditional-04 1032 Ongoing work on ABNF conversion 1033 (): 1035 o Use "/" instead of "|" for alternatives. 1037 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 1038 whitespace ("OWS") and required whitespace ("RWS"). 1040 o Rewrite ABNFs to spell out whitespace rules, factor out header 1041 field value format definitions. 1043 C.7. Since draft-ietf-httpbis-p4-conditional-05 1045 Final work on ABNF conversion 1046 (): 1048 o Add appendix containing collected and expanded ABNF, reorganize 1049 ABNF introduction. 1051 C.8. Since draft-ietf-httpbis-p4-conditional-06 1053 Closed issues: 1055 o : "case- 1056 sensitivity of etag weakness indicator" 1058 C.9. Since draft-ietf-httpbis-p4-conditional-07 1060 Closed issues: 1062 o : "Weak ETags on 1063 non-GET requests" (If-Match still was defined to require strong 1064 matching) 1066 o : "move IANA 1067 registrations for optional status codes" 1069 C.10. Since draft-ietf-httpbis-p4-conditional-08 1071 No significant changes. 1073 C.11. Since draft-ietf-httpbis-p4-conditional-09 1075 No significant changes. 1077 C.12. Since draft-ietf-httpbis-p4-conditional-10 1079 Closed issues: 1081 o : "Clarify 1082 'Requested Variant'" 1084 o : "Clarify 1085 entity / representation / variant terminology" 1087 o : "consider 1088 removing the 'changes from 2068' sections" 1090 C.13. Since draft-ietf-httpbis-p4-conditional-11 1092 None. 1094 C.14. Since draft-ietf-httpbis-p4-conditional-12 1096 Closed issues: 1098 o : "Header 1099 Classification" 1101 C.15. Since draft-ietf-httpbis-p4-conditional-13 1103 Closed issues: 1105 o : "If-* and 1106 entities" 1108 o : "Definition of 1109 validator weakness" 1111 o : "untangle 1112 ABNFs for header fields" 1114 o : "ETags and 1115 Quotes" 1117 Index 1119 3 1120 304 Not Modified (status code) 18 1122 4 1123 412 Precondition Failed (status code) 19 1125 E 1126 ETag header field 8 1128 G 1129 Grammar 1130 entity-tag 8 1131 ETag 8 1132 If-Match 14 1133 If-Modified-Since 16 1134 If-None-Match 15 1135 If-Unmodified-Since 18 1136 Last-Modified 6 1137 opaque-tag 8 1138 weak 8 1140 H 1141 Header Fields 1142 ETag 8 1143 If-Match 14 1144 If-Modified-Since 16 1145 If-None-Match 15 1146 If-Unmodified-Since 18 1147 Last-Modified 6 1149 I 1150 If-Match header field 14 1151 If-Modified-Since header field 16 1152 If-None-Match header field 15 1153 If-Unmodified-Since header field 18 1155 L 1156 Last-Modified header field 6 1158 M 1159 metadata 6 1161 S 1162 selected representation 5 1163 Status Codes 1164 304 Not Modified 18 1165 412 Precondition Failed 19 1167 V 1168 validator 6 1170 Authors' Addresses 1172 Roy T. Fielding (editor) 1173 Adobe Systems Incorporated 1174 345 Park Ave 1175 San Jose, CA 95110 1176 USA 1178 EMail: fielding@gbiv.com 1179 URI: http://roy.gbiv.com/ 1180 Jim Gettys 1181 Alcatel-Lucent Bell Labs 1182 21 Oak Knoll Road 1183 Carlisle, MA 01741 1184 USA 1186 EMail: jg@freedesktop.org 1187 URI: http://gettys.wordpress.com/ 1189 Jeffrey C. Mogul 1190 Hewlett-Packard Company 1191 HP Labs, Large Scale Systems Group 1192 1501 Page Mill Road, MS 1177 1193 Palo Alto, CA 94304 1194 USA 1196 EMail: JeffMogul@acm.org 1198 Henrik Frystyk Nielsen 1199 Microsoft Corporation 1200 1 Microsoft Way 1201 Redmond, WA 98052 1202 USA 1204 EMail: henrikn@microsoft.com 1206 Larry Masinter 1207 Adobe Systems Incorporated 1208 345 Park Ave 1209 San Jose, CA 95110 1210 USA 1212 EMail: LMM@acm.org 1213 URI: http://larry.masinter.net/ 1215 Paul J. Leach 1216 Microsoft Corporation 1217 1 Microsoft Way 1218 Redmond, WA 98052 1220 EMail: paulle@microsoft.com 1221 Tim Berners-Lee 1222 World Wide Web Consortium 1223 MIT Computer Science and Artificial Intelligence Laboratory 1224 The Stata Center, Building 32 1225 32 Vassar Street 1226 Cambridge, MA 02139 1227 USA 1229 EMail: timbl@w3.org 1230 URI: http://www.w3.org/People/Berners-Lee/ 1232 Yves Lafon (editor) 1233 World Wide Web Consortium 1234 W3C / ERCIM 1235 2004, rte des Lucioles 1236 Sophia-Antipolis, AM 06902 1237 France 1239 EMail: ylafon@w3.org 1240 URI: http://www.raubacapeu.net/people/yves/ 1242 Julian F. Reschke (editor) 1243 greenbytes GmbH 1244 Hafenweg 16 1245 Muenster, NW 48155 1246 Germany 1248 Phone: +49 251 2807760 1249 Fax: +49 251 2807761 1250 EMail: julian.reschke@greenbytes.de 1251 URI: http://greenbytes.de/tech/webdav/