idnits 2.17.1 draft-ietf-httpbis-p4-conditional-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 30. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1042. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1053. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1060. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1066. 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 16, 2008) is 5637 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-05 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-05 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-05 -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fielding, Ed. 3 Internet-Draft Day Software 4 Obsoletes: 2616 (if approved) J. Gettys 5 Intended status: Standards Track One Laptop per Child 6 Expires: May 20, 2009 J. Mogul 7 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe Systems 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 November 16, 2008 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-05 25 Status of this Memo 27 By submitting this Internet-Draft, each author represents that any 28 applicable patent or other IPR claims of which he or she is aware 29 have been or will be disclosed, and any of which he or she becomes 30 aware will be disclosed, in accordance with Section 6 of BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF), its areas, and its working groups. Note that 34 other groups may also distribute working documents as Internet- 35 Drafts. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 The list of current Internet-Drafts can be accessed at 43 http://www.ietf.org/ietf/1id-abstracts.txt. 45 The list of Internet-Draft Shadow Directories can be accessed at 46 http://www.ietf.org/shadow.html. 48 This Internet-Draft will expire on May 20, 2009. 50 Abstract 52 The Hypertext Transfer Protocol (HTTP) is an application-level 53 protocol for distributed, collaborative, hypermedia information 54 systems. HTTP has been in use by the World Wide Web global 55 information initiative since 1990. This document is Part 4 of the 56 seven-part specification that defines the protocol referred to as 57 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 4 defines 58 request header fields for indicating conditional requests and the 59 rules for constructing responses to those requests. 61 Editorial Note (To be removed by RFC Editor) 63 Discussion of this draft should take place on the HTTPBIS working 64 group mailing list (ietf-http-wg@w3.org). The current issues list is 65 at and related 66 documents (including fancy diffs) can be found at 67 . 69 The changes in this draft are summarized in Appendix B.6. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 74 1.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 75 2. Notational Conventions and Generic Grammar . . . . . . . . . . 4 76 3. Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . 5 77 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 5 78 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 5 79 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 6 80 5. Weak and Strong Validators . . . . . . . . . . . . . . . . . . 6 81 6. Rules for When to Use Entity Tags and Last-Modified Dates . . 9 82 7. Header Field Definitions . . . . . . . . . . . . . . . . . . . 11 83 7.1. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 7.2. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 12 85 7.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 13 86 7.4. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 14 87 7.5. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 16 88 7.6. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 16 89 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 90 8.1. Message Header Registration . . . . . . . . . . . . . . . 17 91 9. Security Considerations . . . . . . . . . . . . . . . . . . . 18 92 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 93 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 94 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 95 11.2. Informative References . . . . . . . . . . . . . . . . . . 18 96 Appendix A. Compatibility with Previous Versions . . . . . . . . 18 97 A.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 19 98 Appendix B. Change Log (to be removed by RFC Editor before 99 publication) . . . . . . . . . . . . . . . . . . . . 19 100 B.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 19 101 B.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 19 102 B.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 19 103 B.4. Since draft-ietf-httpbis-p4-conditional-02 . . . . . . . . 19 104 B.5. Since draft-ietf-httpbis-p4-conditional-03 . . . . . . . . 20 105 B.6. Since draft-ietf-httpbis-p4-conditional-04 . . . . . . . . 20 106 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 108 Intellectual Property and Copyright Statements . . . . . . . . . . 24 110 1. Introduction 112 This document defines HTTP/1.1 response metadata for indicating 113 potential changes to payload content, including modification time 114 stamps and opaque entity-tags, and the HTTP conditional request 115 mechanisms that allow preconditions to be placed on a request method. 116 Conditional GET requests allow for efficient cache updates. Other 117 conditional request methods are used to protect against overwriting 118 or misunderstanding the state of a resource that has been changed 119 unbeknownst to the requesting client. 121 This document is currently disorganized in order to minimize the 122 changes between drafts and enable reviewers to see the smaller errata 123 changes. The next draft will reorganize the sections to better 124 reflect the content. In particular, the sections on resource 125 metadata will be discussed first and then followed by each 126 conditional request-header, concluding with a definition of 127 precedence and the expectation of ordering strong validator checks 128 before weak validator checks. It is likely that more content from 129 [Part6] will migrate to this part, where appropriate. The current 130 mess reflects how widely dispersed these topics and associated 131 requirements had become in [RFC2616]. 133 1.1. Requirements 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 137 document are to be interpreted as described in [RFC2119]. 139 An implementation is not compliant if it fails to satisfy one or more 140 of the MUST or REQUIRED level requirements for the protocols it 141 implements. An implementation that satisfies all the MUST or 142 REQUIRED level and all the SHOULD level requirements for its 143 protocols is said to be "unconditionally compliant"; one that 144 satisfies all the MUST level requirements but not all the SHOULD 145 level requirements for its protocols is said to be "conditionally 146 compliant." 148 2. Notational Conventions and Generic Grammar 150 This specification uses the ABNF syntax defined in Section 2.1 of 151 [Part1] and the core rules defined in Section 2.2 of [Part1]: 153 quoted-string = 154 OWS = 156 The ABNF rules below are defined in other parts: 158 HTTP-date = 160 3. Entity Tags 162 Entity tags are used for comparing two or more entities from the same 163 requested resource. HTTP/1.1 uses entity tags in the ETag 164 (Section 7.1), If-Match (Section 7.2), If-None-Match (Section 7.4), 165 and If-Range (Section 6.3 of [Part5]) header fields. The definition 166 of how they are used and compared as cache validators is in 167 Section 5. An entity tag consists of an opaque quoted string, 168 possibly prefixed by a weakness indicator. 170 entity-tag = [ weak ] opaque-tag 171 weak = "W/" 172 opaque-tag = quoted-string 174 A "strong entity tag" MAY be shared by two entities of a resource 175 only if they are equivalent by octet equality. 177 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 178 two entities of a resource only if the entities are equivalent and 179 could be substituted for each other with no significant change in 180 semantics. A weak entity tag can only be used for weak comparison. 182 An entity tag MUST be unique across all versions of all entities 183 associated with a particular resource. A given entity tag value MAY 184 be used for entities obtained by requests on different URIs. The use 185 of the same entity tag value in conjunction with entities obtained by 186 requests on different URIs does not imply the equivalence of those 187 entities. 189 4. Status Code Definitions 191 4.1. 304 Not Modified 193 If the client has performed a conditional GET request and access is 194 allowed, but the document has not been modified, the server SHOULD 195 respond with this status code. The 304 response MUST NOT contain a 196 message-body, and thus is always terminated by the first empty line 197 after the header fields. 199 The response MUST include the following header fields: 201 o Date, unless its omission is required by Section 8.3.1 of [Part1]. 203 If a clockless origin server obeys these rules, and proxies and 204 clients add their own Date to any response received without one 205 (as already specified by Section 8.3 of [Part1], caches will 206 operate correctly. 208 o ETag and/or Content-Location, if the header would have been sent 209 in a 200 response to the same request. 211 o Expires, Cache-Control, and/or Vary, if the field-value might 212 differ from that sent in any previous response for the same 213 variant. 215 If the conditional GET used a strong cache validator (see Section 5), 216 the response SHOULD NOT include other entity-headers. Otherwise 217 (i.e., the conditional GET used a weak validator), the response MUST 218 NOT include other entity-headers; this prevents inconsistencies 219 between cached entity-bodies and updated headers. 221 If a 304 response indicates an entity not currently cached, then the 222 cache MUST disregard the response and repeat the request without the 223 conditional. 225 If a cache uses a received 304 response to update a cache entry, the 226 cache MUST update the entry to reflect any new field values given in 227 the response. 229 4.2. 412 Precondition Failed 231 The precondition given in one or more of the request-header fields 232 evaluated to false when it was tested on the server. This response 233 code allows the client to place preconditions on the current resource 234 metainformation (header field data) and thus prevent the requested 235 method from being applied to a resource other than the one intended. 237 5. Weak and Strong Validators 239 Since both origin servers and caches will compare two validators to 240 decide if they represent the same or different entities, one normally 241 would expect that if the entity (the entity-body or any entity- 242 headers) changes in any way, then the associated validator would 243 change as well. If this is true, then we call this validator a 244 "strong validator." 246 However, there might be cases when a server prefers to change the 247 validator only on semantically significant changes, and not when 248 insignificant aspects of the entity change. A validator that does 249 not always change when the resource changes is a "weak validator." 250 Entity tags are normally "strong validators," but the protocol 251 provides a mechanism to tag an entity tag as "weak." One can think 252 of a strong validator as one that changes whenever the bits of an 253 entity changes, while a weak value changes whenever the meaning of an 254 entity changes. Alternatively, one can think of a strong validator 255 as part of an identifier for a specific entity, while a weak 256 validator is part of an identifier for a set of semantically 257 equivalent entities. 259 Note: One example of a strong validator is an integer that is 260 incremented in stable storage every time an entity is changed. 262 An entity's modification time, if represented with one-second 263 resolution, could be a weak validator, since it is possible that 264 the resource might be modified twice during a single second. 266 Support for weak validators is optional. However, weak validators 267 allow for more efficient caching of equivalent objects; for 268 example, a hit counter on a site is probably good enough if it is 269 updated every few days or weeks, and any value during that period 270 is likely "good enough" to be equivalent. 272 A "use" of a validator is either when a client generates a request 273 and includes the validator in a validating header field, or when a 274 server compares two validators. 276 Strong validators are usable in any context. Weak validators are 277 only usable in contexts that do not depend on exact equality of an 278 entity. For example, either kind is usable for a conditional GET of 279 a full entity. However, only a strong validator is usable for a sub- 280 range retrieval, since otherwise the client might end up with an 281 internally inconsistent entity. 283 Clients MUST NOT use weak validators in range requests ([Part5]). 285 The only function that HTTP/1.1 defines on validators is comparison. 286 There are two validator comparison functions, depending on whether 287 the comparison context allows the use of weak validators or not: 289 o The strong comparison function: in order to be considered equal, 290 both opaque-tags MUST be identical character-by-character, and 291 both MUST NOT be weak. 293 o The weak comparison function: in order to be considered equal, 294 both opaque-tags MUST be identical character-by-character. 296 The example below shows the results for a set of entity tag pairs, 297 and both the weak and strong comparison function results: 299 +--------+--------+-------------------+-----------------+ 300 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 301 +--------+--------+-------------------+-----------------+ 302 | W/"1" | W/"1" | no match | match | 303 | W/"1" | W/"2" | no match | no match | 304 | W/"1" | "1" | no match | match | 305 | "1" | "1" | match | match | 306 +--------+--------+-------------------+-----------------+ 308 An entity tag is strong unless it is explicitly tagged as weak. 309 Section 3 gives the syntax for entity tags. 311 A Last-Modified time, when used as a validator in a request, is 312 implicitly weak unless it is possible to deduce that it is strong, 313 using the following rules: 315 o The validator is being compared by an origin server to the actual 316 current validator for the entity and, 318 o That origin server reliably knows that the associated entity did 319 not change twice during the second covered by the presented 320 validator. 322 or 324 o The validator is about to be used by a client in an If-Modified- 325 Since or If-Unmodified-Since header, because the client has a 326 cache entry for the associated entity, and 328 o That cache entry includes a Date value, which gives the time when 329 the origin server sent the original response, and 331 o The presented Last-Modified time is at least 60 seconds before the 332 Date value. 334 or 336 o The validator is being compared by an intermediate cache to the 337 validator stored in its cache entry for the entity, and 339 o That cache entry includes a Date value, which gives the time when 340 the origin server sent the original response, and 342 o The presented Last-Modified time is at least 60 seconds before the 343 Date value. 345 This method relies on the fact that if two different responses were 346 sent by the origin server during the same second, but both had the 347 same Last-Modified time, then at least one of those responses would 348 have a Date value equal to its Last-Modified time. The arbitrary 60- 349 second limit guards against the possibility that the Date and Last- 350 Modified values are generated from different clocks, or at somewhat 351 different times during the preparation of the response. An 352 implementation MAY use a value larger than 60 seconds, if it is 353 believed that 60 seconds is too short. 355 If a client wishes to perform a sub-range retrieval on a value for 356 which it has only a Last-Modified time and no opaque validator, it 357 MAY do this only if the Last-Modified time is strong in the sense 358 described here. 360 A cache or origin server receiving a conditional range request 361 ([Part5]) MUST use the strong comparison function to evaluate the 362 condition. 364 These rules allow HTTP/1.1 caches and clients to safely perform sub- 365 range retrievals on values that have been obtained from HTTP/1.0 366 servers. 368 6. Rules for When to Use Entity Tags and Last-Modified Dates 370 We adopt a set of rules and recommendations for origin servers, 371 clients, and caches regarding when various validator types ought to 372 be used, and for what purposes. 374 HTTP/1.1 origin servers: 376 o SHOULD send an entity tag validator unless it is not feasible to 377 generate one. 379 o MAY send a weak entity tag instead of a strong entity tag, if 380 performance considerations support the use of weak entity tags, or 381 if it is unfeasible to send a strong entity tag. 383 o SHOULD send a Last-Modified value if it is feasible to send one, 384 unless the risk of a breakdown in semantic transparency that could 385 result from using this date in an If-Modified-Since header would 386 lead to serious problems. 388 In other words, the preferred behavior for an HTTP/1.1 origin server 389 is to send both a strong entity tag and a Last-Modified value. 391 In order to be legal, a strong entity tag MUST change whenever the 392 associated entity changes in any way. A weak entity tag SHOULD 393 change whenever the associated entity changes in a semantically 394 significant way. 396 Note: in order to provide semantically transparent caching, an 397 origin server must avoid reusing a specific strong entity tag 398 value for two different entities, or reusing a specific weak 399 entity tag value for two semantically different entities. Cache 400 entries might persist for arbitrarily long periods, regardless of 401 expiration times, so it might be inappropriate to expect that a 402 cache will never again attempt to validate an entry using a 403 validator that it obtained at some point in the past. 405 HTTP/1.1 clients: 407 o If an entity tag has been provided by the origin server, MUST use 408 that entity tag in any cache-conditional request (using If-Match 409 or If-None-Match). 411 o If only a Last-Modified value has been provided by the origin 412 server, SHOULD use that value in non-subrange cache-conditional 413 requests (using If-Modified-Since). 415 o If only a Last-Modified value has been provided by an HTTP/1.0 416 origin server, MAY use that value in subrange cache-conditional 417 requests (using If-Unmodified-Since:). The user agent SHOULD 418 provide a way to disable this, in case of difficulty. 420 o If both an entity tag and a Last-Modified value have been provided 421 by the origin server, SHOULD use both validators in cache- 422 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 423 caches to respond appropriately. 425 An HTTP/1.1 origin server, upon receiving a conditional request that 426 includes both a Last-Modified date (e.g., in an If-Modified-Since or 427 If-Unmodified-Since header field) and one or more entity tags (e.g., 428 in an If-Match, If-None-Match, or If-Range header field) as cache 429 validators, MUST NOT return a response status of 304 (Not Modified) 430 unless doing so is consistent with all of the conditional header 431 fields in the request. 433 An HTTP/1.1 caching proxy, upon receiving a conditional request that 434 includes both a Last-Modified date and one or more entity tags as 435 cache validators, MUST NOT return a locally cached response to the 436 client unless that cached response is consistent with all of the 437 conditional header fields in the request. 439 Note: The general principle behind these rules is that HTTP/1.1 440 servers and clients should transmit as much non-redundant 441 information as is available in their responses and requests. 443 HTTP/1.1 systems receiving this information will make the most 444 conservative assumptions about the validators they receive. 446 HTTP/1.0 clients and caches will ignore entity tags. Generally, 447 last-modified values received or used by these systems will 448 support transparent and efficient caching, and so HTTP/1.1 origin 449 servers should provide Last-Modified values. In those rare cases 450 where the use of a Last-Modified value as a validator by an 451 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 452 origin servers should not provide one. 454 7. Header Field Definitions 456 This section defines the syntax and semantics of HTTP/1.1 header 457 fields related to conditional requests. 459 For entity-header fields, both sender and recipient refer to either 460 the client or the server, depending on who sends and who receives the 461 entity. 463 7.1. ETag 465 The response-header field "ETag" provides the current value of the 466 entity tag (see Section 3) for the requested variant. The headers 467 used with entity tags are described in Sections 7.2 and 7.4 of this 468 document, and in Section 6.3 of [Part5]. The entity tag MAY be used 469 for comparison with other entities from the same resource (see 470 Section 5). 472 ETag = "ETag" ":" OWS ETag-v 473 ETag-v = entity-tag 475 Examples: 477 ETag: "xyzzy" 478 ETag: W/"xyzzy" 479 ETag: "" 481 The ETag response-header field value, an entity tag, provides for an 482 "opaque" cache validator. This might allow more reliable validation 483 in situations where it is inconvenient to store modification dates, 484 where the one-second resolution of HTTP date values is not 485 sufficient, or where the origin server wishes to avoid certain 486 paradoxes that might arise from the use of modification dates. 488 The principle behind entity tags is that only the service author 489 knows the semantics of a resource well enough to select an 490 appropriate cache validation mechanism, and the specification of any 491 validator comparison function more complex than byte-equality would 492 open up a can of worms. Thus, comparisons of any other headers 493 (except Last-Modified, for compatibility with HTTP/1.0) are never 494 used for purposes of validating a cache entry. 496 7.2. If-Match 498 The request-header field "If-Match" is used with a method to make it 499 conditional. A client that has one or more entities previously 500 obtained from the resource can verify that one of those entities is 501 current by including a list of their associated entity tags in the 502 If-Match header field. Entity tags are defined in Section 3. The 503 purpose of this feature is to allow efficient updates of cached 504 information with a minimum amount of transaction overhead. It is 505 also used, on updating requests, to prevent inadvertent modification 506 of the wrong version of a resource. As a special case, the value "*" 507 matches any current entity of the resource. 509 If-Match = "If-Match" ":" OWS If-Match-v 510 If-Match-v = "*" / 1#entity-tag 512 If any of the entity tags match the entity tag of the entity that 513 would have been returned in the response to a similar GET request 514 (without the If-Match header) on that resource, or if "*" is given 515 and any current entity exists for that resource, then the server MAY 516 perform the requested method as if the If-Match header field did not 517 exist. 519 A server MUST use the strong comparison function (see Section 5) to 520 compare the entity tags in If-Match. 522 If none of the entity tags match, or if "*" is given and no current 523 entity exists, the server MUST NOT perform the requested method, and 524 MUST return a 412 (Precondition Failed) response. This behavior is 525 most useful when the client wants to prevent an updating method, such 526 as PUT, from modifying a resource that has changed since the client 527 last retrieved it. 529 If the request would, without the If-Match header field, result in 530 anything other than a 2xx or 412 status, then the If-Match header 531 MUST be ignored. 533 The meaning of "If-Match: *" is that the method SHOULD be performed 534 if the representation selected by the origin server (or by a cache, 535 possibly using the Vary mechanism, see Section 16.5 of [Part6]) 536 exists, and MUST NOT be performed if the representation does not 537 exist. 539 A request intended to update a resource (e.g., a PUT) MAY include an 540 If-Match header field to signal that the request method MUST NOT be 541 applied if the entity corresponding to the If-Match value (a single 542 entity tag) is no longer a representation of that resource. This 543 allows the user to indicate that they do not wish the request to be 544 successful if the resource has been changed without their knowledge. 545 Examples: 547 If-Match: "xyzzy" 548 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 549 If-Match: * 551 The result of a request having both an If-Match header field and 552 either an If-None-Match or an If-Modified-Since header fields is 553 undefined by this specification. 555 7.3. If-Modified-Since 557 The request-header field "If-Modified-Since" is used with a method to 558 make it conditional: if the requested variant has not been modified 559 since the time specified in this field, an entity will not be 560 returned from the server; instead, a 304 (Not Modified) response will 561 be returned without any message-body. 563 If-Modified-Since = "If-Modified-Since" ":" OWS 564 If-Modified-Since-v 565 If-Modified-Since-v = HTTP-date 567 An example of the field is: 569 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 571 A GET method with an If-Modified-Since header and no Range header 572 requests that the identified entity be transferred only if it has 573 been modified since the date given by the If-Modified-Since header. 574 The algorithm for determining this includes the following cases: 576 1. If the request would normally result in anything other than a 200 577 (OK) status, or if the passed If-Modified-Since date is invalid, 578 the response is exactly the same as for a normal GET. A date 579 which is later than the server's current time is invalid. 581 2. If the variant has been modified since the If-Modified-Since 582 date, the response is exactly the same as for a normal GET. 584 3. If the variant has not been modified since a valid If-Modified- 585 Since date, the server SHOULD return a 304 (Not Modified) 586 response. 588 The purpose of this feature is to allow efficient updates of cached 589 information with a minimum amount of transaction overhead. 591 Note: The Range request-header field modifies the meaning of If- 592 Modified-Since; see Section 6.4 of [Part5] for full details. 594 Note: If-Modified-Since times are interpreted by the server, whose 595 clock might not be synchronized with the client. 597 Note: When handling an If-Modified-Since header field, some 598 servers will use an exact date comparison function, rather than a 599 less-than function, for deciding whether to send a 304 (Not 600 Modified) response. To get best results when sending an If- 601 Modified-Since header field for cache validation, clients are 602 advised to use the exact date string received in a previous Last- 603 Modified header field whenever possible. 605 Note: If a client uses an arbitrary date in the If-Modified-Since 606 header instead of a date taken from the Last-Modified header for 607 the same request, the client should be aware of the fact that this 608 date is interpreted in the server's understanding of time. The 609 client should consider unsynchronized clocks and rounding problems 610 due to the different encodings of time between the client and 611 server. This includes the possibility of race conditions if the 612 document has changed between the time it was first requested and 613 the If-Modified-Since date of a subsequent request, and the 614 possibility of clock-skew-related problems if the If-Modified- 615 Since date is derived from the client's clock without correction 616 to the server's clock. Corrections for different time bases 617 between client and server are at best approximate due to network 618 latency. 620 The result of a request having both an If-Modified-Since header field 621 and either an If-Match or an If-Unmodified-Since header fields is 622 undefined by this specification. 624 7.4. If-None-Match 626 The request-header field "If-None-Match" is used with a method to 627 make it conditional. A client that has one or more entities 628 previously obtained from the resource can verify that none of those 629 entities is current by including a list of their associated entity 630 tags in the If-None-Match header field. The purpose of this feature 631 is to allow efficient updates of cached information with a minimum 632 amount of transaction overhead. It is also used to prevent a method 633 (e.g. PUT) from inadvertently modifying an existing resource when 634 the client believes that the resource does not exist. 636 As a special case, the value "*" matches any current entity of the 637 resource. 639 If-None-Match = "If-None-Match" ":" OWS If-None-Match-v 640 If-None-Match-v = "*" / 1#entity-tag 642 If any of the entity tags match the entity tag of the entity that 643 would have been returned in the response to a similar GET request 644 (without the If-None-Match header) on that resource, or if "*" is 645 given and any current entity exists for that resource, then the 646 server MUST NOT perform the requested method, unless required to do 647 so because the resource's modification date fails to match that 648 supplied in an If-Modified-Since header field in the request. 649 Instead, if the request method was GET or HEAD, the server SHOULD 650 respond with a 304 (Not Modified) response, including the cache- 651 related header fields (particularly ETag) of one of the entities that 652 matched. For all other request methods, the server MUST respond with 653 a status of 412 (Precondition Failed). 655 See Section 5 for rules on how to determine if two entity tags match. 657 If none of the entity tags match, then the server MAY perform the 658 requested method as if the If-None-Match header field did not exist, 659 but MUST also ignore any If-Modified-Since header field(s) in the 660 request. That is, if no entity tags match, then the server MUST NOT 661 return a 304 (Not Modified) response. 663 If the request would, without the If-None-Match header field, result 664 in anything other than a 2xx or 304 status, then the If-None-Match 665 header MUST be ignored. (See Section 6 for a discussion of server 666 behavior when both If-Modified-Since and If-None-Match appear in the 667 same request.) 669 The meaning of "If-None-Match: *" is that the method MUST NOT be 670 performed if the representation selected by the origin server (or by 671 a cache, possibly using the Vary mechanism, see Section 16.5 of 672 [Part6]) exists, and SHOULD be performed if the representation does 673 not exist. This feature is intended to be useful in preventing races 674 between PUT operations. 676 Examples: 678 If-None-Match: "xyzzy" 679 If-None-Match: W/"xyzzy" 680 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 681 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 682 If-None-Match: * 684 The result of a request having both an If-None-Match header field and 685 either an If-Match or an If-Unmodified-Since header fields is 686 undefined by this specification. 688 7.5. If-Unmodified-Since 690 The request-header field "If-Unmodified-Since" is used with a method 691 to make it conditional. If the requested resource has not been 692 modified since the time specified in this field, the server SHOULD 693 perform the requested operation as if the If-Unmodified-Since header 694 were not present. 696 If the requested variant has been modified since the specified time, 697 the server MUST NOT perform the requested operation, and MUST return 698 a 412 (Precondition Failed). 700 If-Unmodified-Since = "If-Unmodified-Since" ":" OWS 701 If-Unmodified-Since-v 702 If-Unmodified-Since-v = HTTP-date 704 An example of the field is: 706 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 708 If the request normally (i.e., without the If-Unmodified-Since 709 header) would result in anything other than a 2xx or 412 status, the 710 If-Unmodified-Since header SHOULD be ignored. 712 If the specified date is invalid, the header is ignored. 714 The result of a request having both an If-Unmodified-Since header 715 field and either an If-None-Match or an If-Modified-Since header 716 fields is undefined by this specification. 718 7.6. Last-Modified 720 The entity-header field "Last-Modified" indicates the date and time 721 at which the origin server believes the variant was last modified. 723 Last-Modified = "Last-Modified" ":" OWS Last-Modified-v 724 Last-Modified-v = HTTP-date 726 An example of its use is 728 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 730 The exact meaning of this header field depends on the implementation 731 of the origin server and the nature of the original resource. For 732 files, it may be just the file system last-modified time. For 733 entities with dynamically included parts, it may be the most recent 734 of the set of last-modify times for its component parts. For 735 database gateways, it may be the last-update time stamp of the 736 record. For virtual objects, it may be the last time the internal 737 state changed. 739 An origin server MUST NOT send a Last-Modified date which is later 740 than the server's time of message origination. In such cases, where 741 the resource's last modification would indicate some time in the 742 future, the server MUST replace that date with the message 743 origination date. 745 An origin server SHOULD obtain the Last-Modified value of the entity 746 as close as possible to the time that it generates the Date value of 747 its response. This allows a recipient to make an accurate assessment 748 of the entity's modification time, especially if the entity changes 749 near the time that the response is generated. 751 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 753 The Last-Modified entity-header field value is often used as a cache 754 validator. In simple terms, a cache entry is considered to be valid 755 if the entity has not been modified since the Last-Modified value. 757 8. IANA Considerations 759 8.1. Message Header Registration 761 The Message Header Registry located at should be 763 updated with the permanent registrations below (see [RFC3864]): 765 +---------------------+----------+----------+-------------+ 766 | Header Field Name | Protocol | Status | Reference | 767 +---------------------+----------+----------+-------------+ 768 | ETag | http | standard | Section 7.1 | 769 | If-Match | http | standard | Section 7.2 | 770 | If-Modified-Since | http | standard | Section 7.3 | 771 | If-None-Match | http | standard | Section 7.4 | 772 | If-Unmodified-Since | http | standard | Section 7.5 | 773 | Last-Modified | http | standard | Section 7.6 | 774 +---------------------+----------+----------+-------------+ 776 The change controller is: "IETF (iesg@ietf.org) - Internet 777 Engineering Task Force". 779 9. Security Considerations 781 No additional security considerations have been identified beyond 782 those applicable to HTTP in general [Part1]. 784 10. Acknowledgments 786 11. References 788 11.1. Normative References 790 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 791 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 792 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 793 and Message Parsing", draft-ietf-httpbis-p1-messaging-05 794 (work in progress), November 2008. 796 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 797 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 798 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 799 Partial Responses", draft-ietf-httpbis-p5-range-05 (work 800 in progress), November 2008. 802 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 803 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 804 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 805 draft-ietf-httpbis-p6-cache-05 (work in progress), 806 November 2008. 808 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 809 Requirement Levels", BCP 14, RFC 2119, March 1997. 811 11.2. Informative References 813 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 814 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 815 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 817 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 818 Procedures for Message Header Fields", BCP 90, RFC 3864, 819 September 2004. 821 Appendix A. Compatibility with Previous Versions 822 A.1. Changes from RFC 2616 824 Allow weak entity tags in all requests except range requests 825 (Sections 5 and 7.4). 827 Appendix B. Change Log (to be removed by RFC Editor before publication) 829 B.1. Since RFC2616 831 Extracted relevant partitions from [RFC2616]. 833 B.2. Since draft-ietf-httpbis-p4-conditional-00 835 Closed issues: 837 o : "Normative and 838 Informative references" 840 Other changes: 842 o Move definitions of 304 and 412 condition codes from Part2. 844 B.3. Since draft-ietf-httpbis-p4-conditional-01 846 Ongoing work on ABNF conversion 847 (): 849 o Add explicit references to BNF syntax and rules imported from 850 other parts of the specification. 852 B.4. Since draft-ietf-httpbis-p4-conditional-02 854 Closed issues: 856 o : "Weak ETags on 857 non-GET requests" 859 Ongoing work on IANA Message Header Registration 860 (): 862 o Reference RFC 3984, and update header registrations for headers 863 defined in this document. 865 B.5. Since draft-ietf-httpbis-p4-conditional-03 867 Closed issues: 869 o : "Examples for 870 ETag matching" 872 o : "'entity 873 value' undefined" 875 o : "bogus 2068 876 Date header reference" 878 B.6. Since draft-ietf-httpbis-p4-conditional-04 880 Ongoing work on ABNF conversion 881 (): 883 o Use "/" instead of "|" for alternatives. 885 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional 886 whitespace ("OWS") and required whitespace ("RWS"). 888 o Rewrite ABNFs to spell out whitespace rules, factor out header 889 value format definitions. 891 Index 893 3 894 304 Not Modified (status code) 5 896 4 897 412 Precondition Failed (status code) 6 899 E 900 ETag header 11 902 G 903 Grammar 904 entity-tag 5 905 ETag 11 906 ETag-v 11 907 If-Match 12 908 If-Match-v 12 909 If-Modified-Since 13 910 If-Modified-Since-v 13 911 If-None-Match 15 912 If-None-Match-v 15 913 If-Unmodified-Since 16 914 If-Unmodified-Since-v 16 915 Last-Modified 16 916 Last-Modified-v 16 917 opaque-tag 5 918 weak 5 920 H 921 Headers 922 ETag 11 923 If-Match 12 924 If-Modified-Since 13 925 If-None-Match 14 926 If-Unmodified-Since 16 927 Last-Modified 16 929 I 930 If-Match header 12 931 If-Modified-Since header 13 932 If-None-Match header 14 933 If-Unmodified-Since header 16 935 L 936 Last-Modified header 16 938 S 939 Status Codes 940 304 Not Modified 5 941 412 Precondition Failed 6 943 Authors' Addresses 945 Roy T. Fielding (editor) 946 Day Software 947 23 Corporate Plaza DR, Suite 280 948 Newport Beach, CA 92660 949 USA 951 Phone: +1-949-706-5300 952 Fax: +1-949-706-5305 953 Email: fielding@gbiv.com 954 URI: http://roy.gbiv.com/ 955 Jim Gettys 956 One Laptop per Child 957 21 Oak Knoll Road 958 Carlisle, MA 01741 959 USA 961 Email: jg@laptop.org 962 URI: http://www.laptop.org/ 964 Jeffrey C. Mogul 965 Hewlett-Packard Company 966 HP Labs, Large Scale Systems Group 967 1501 Page Mill Road, MS 1177 968 Palo Alto, CA 94304 969 USA 971 Email: JeffMogul@acm.org 973 Henrik Frystyk Nielsen 974 Microsoft Corporation 975 1 Microsoft Way 976 Redmond, WA 98052 977 USA 979 Email: henrikn@microsoft.com 981 Larry Masinter 982 Adobe Systems, Incorporated 983 345 Park Ave 984 San Jose, CA 95110 985 USA 987 Email: LMM@acm.org 988 URI: http://larry.masinter.net/ 990 Paul J. Leach 991 Microsoft Corporation 992 1 Microsoft Way 993 Redmond, WA 98052 995 Email: paulle@microsoft.com 996 Tim Berners-Lee 997 World Wide Web Consortium 998 MIT Computer Science and Artificial Intelligence Laboratory 999 The Stata Center, Building 32 1000 32 Vassar Street 1001 Cambridge, MA 02139 1002 USA 1004 Email: timbl@w3.org 1005 URI: http://www.w3.org/People/Berners-Lee/ 1007 Yves Lafon (editor) 1008 World Wide Web Consortium 1009 W3C / ERCIM 1010 2004, rte des Lucioles 1011 Sophia-Antipolis, AM 06902 1012 France 1014 Email: ylafon@w3.org 1015 URI: http://www.raubacapeu.net/people/yves/ 1017 Julian F. Reschke (editor) 1018 greenbytes GmbH 1019 Hafenweg 16 1020 Muenster, NW 48155 1021 Germany 1023 Phone: +49 251 2807760 1024 Fax: +49 251 2807761 1025 Email: julian.reschke@greenbytes.de 1026 URI: http://greenbytes.de/tech/webdav/ 1028 Full Copyright Statement 1030 Copyright (C) The IETF Trust (2008). 1032 This document is subject to the rights, licenses and restrictions 1033 contained in BCP 78, and except as set forth therein, the authors 1034 retain all their rights. 1036 This document and the information contained herein are provided on an 1037 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1038 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1039 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1040 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1041 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1042 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1044 Intellectual Property 1046 The IETF takes no position regarding the validity or scope of any 1047 Intellectual Property Rights or other rights that might be claimed to 1048 pertain to the implementation or use of the technology described in 1049 this document or the extent to which any license under such rights 1050 might or might not be available; nor does it represent that it has 1051 made any independent effort to identify any such rights. Information 1052 on the procedures with respect to rights in RFC documents can be 1053 found in BCP 78 and BCP 79. 1055 Copies of IPR disclosures made to the IETF Secretariat and any 1056 assurances of licenses to be made available, or the result of an 1057 attempt made to obtain a general license or permission for the use of 1058 such proprietary rights by implementers or users of this 1059 specification can be obtained from the IETF on-line IPR repository at 1060 http://www.ietf.org/ipr. 1062 The IETF invites any interested party to bring to its attention any 1063 copyrights, patents or patent applications, or other proprietary 1064 rights that may cover technology that may be required to implement 1065 this standard. Please address the information to the IETF at 1066 ietf-ipr@ietf.org.