idnits 2.17.1 draft-ietf-httpbis-p4-conditional-02.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 967. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 978. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 985. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 991. 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 (February 24, 2008) is 5905 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-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-02 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-02 -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- 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 (==), 9 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: August 27, 2008 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 February 24, 2008 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-02 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 August 27, 2008. 50 Copyright Notice 52 Copyright (C) The IETF Trust (2008). 54 Abstract 56 The Hypertext Transfer Protocol (HTTP) is an application-level 57 protocol for distributed, collaborative, hypermedia information 58 systems. HTTP has been in use by the World Wide Web global 59 information initiative since 1990. This document is Part 4 of the 60 seven-part specification that defines the protocol referred to as 61 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 4 defines 62 request header fields for indicating conditional requests and the 63 rules for constructing responses to those requests. 65 Editorial Note (To be removed by RFC Editor) 67 Discussion of this draft should take place on the HTTPBIS working 68 group mailing list (ietf-http-wg@w3.org). The current issues list is 69 at and related 70 documents (including fancy diffs) can be found at 71 . 73 This draft incorporates those issue resolutions that were either 74 collected in the original RFC2616 errata list 75 (), or which were agreed upon on the 76 mailing list between October 2006 and November 2007 (as published in 77 "draft-lafon-rfc2616bis-03"). 79 Table of Contents 81 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 82 1.1. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 83 2. Notational Conventions and Generic Grammar . . . . . . . . . . 4 84 3. Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . 5 85 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 5 86 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 5 87 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 6 88 5. Weak and Strong Validators . . . . . . . . . . . . . . . . . . 6 89 6. Rules for When to Use Entity Tags and Last-Modified Dates . . 9 90 7. Header Field Definitions . . . . . . . . . . . . . . . . . . . 11 91 7.1. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 92 7.2. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 12 93 7.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 13 94 7.4. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 14 95 7.5. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 16 96 7.6. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 16 97 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 98 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 99 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 100 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 101 11.1. Normative References . . . . . . . . . . . . . . . . . . . 17 102 11.2. Informative References . . . . . . . . . . . . . . . . . . 18 103 Appendix A. Compatibility with Previous Versions . . . . . . . . 18 104 A.1. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 18 105 Appendix B. Change Log (to be removed by RFC Editor before 106 publication) . . . . . . . . . . . . . . . . . . . . 18 107 B.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 18 108 B.2. Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 18 109 B.3. Since draft-ietf-httpbis-p4-conditional-01 . . . . . . . . 18 110 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 112 Intellectual Property and Copyright Statements . . . . . . . . . . 23 114 1. Introduction 116 This document defines HTTP/1.1 response metadata for indicating 117 potential changes to payload content, including modification time 118 stamps and opaque entity-tags, and the HTTP conditional request 119 mechanisms that allow preconditions to be placed on a request method. 120 Conditional GET requests allow for efficient cache updates. Other 121 conditional request methods are used to protect against overwriting 122 or misunderstanding the state of a resource that has been changed 123 unbeknownst to the requesting client. 125 This document is currently disorganized in order to minimize the 126 changes between drafts and enable reviewers to see the smaller errata 127 changes. The next draft will reorganize the sections to better 128 reflect the content. In particular, the sections on resource 129 metadata will be discussed first and then followed by each 130 conditional request-header, concluding with a definition of 131 precedence and the expectation of ordering strong validator checks 132 before weak validator checks. It is likely that more content from 133 [Part6] will migrate to this part, where appropriate. The current 134 mess reflects how widely dispersed these topics and associated 135 requirements had become in [RFC2616]. 137 1.1. Requirements 139 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 140 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 141 document are to be interpreted as described in [RFC2119]. 143 An implementation is not compliant if it fails to satisfy one or more 144 of the MUST or REQUIRED level requirements for the protocols it 145 implements. An implementation that satisfies all the MUST or 146 REQUIRED level and all the SHOULD level requirements for its 147 protocols is said to be "unconditionally compliant"; one that 148 satisfies all the MUST level requirements but not all the SHOULD 149 level requirements for its protocols is said to be "conditionally 150 compliant." 152 2. Notational Conventions and Generic Grammar 154 This specification uses the ABNF syntax defined in Section 2.1 of 155 [Part1] and the core rules defined in Section 2.2 of [Part1]: 156 [[abnf.dep: ABNF syntax and basic rules will be adopted from RFC 157 5234, see .]] 159 quoted-string = 161 The ABNF rules below are defined in other parts: 163 HTTP-date = 165 3. Entity Tags 167 Entity tags are used for comparing two or more entities from the same 168 requested resource. HTTP/1.1 uses entity tags in the ETag 169 (Section 7.1), If-Match (Section 7.2), If-None-Match (Section 7.4), 170 and If-Range (Section 6.3 of [Part5]) header fields. The definition 171 of how they are used and compared as cache validators is in 172 Section 5. An entity tag consists of an opaque quoted string, 173 possibly prefixed by a weakness indicator. 175 entity-tag = [ weak ] opaque-tag 176 weak = "W/" 177 opaque-tag = quoted-string 179 A "strong entity tag" MAY be shared by two entities of a resource 180 only if they are equivalent by octet equality. 182 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 183 two entities of a resource only if the entities are equivalent and 184 could be substituted for each other with no significant change in 185 semantics. A weak entity tag can only be used for weak comparison. 187 An entity tag MUST be unique across all versions of all entities 188 associated with a particular resource. A given entity tag value MAY 189 be used for entities obtained by requests on different URIs. The use 190 of the same entity tag value in conjunction with entities obtained by 191 requests on different URIs does not imply the equivalence of those 192 entities. 194 4. Status Code Definitions 196 4.1. 304 Not Modified 198 If the client has performed a conditional GET request and access is 199 allowed, but the document has not been modified, the server SHOULD 200 respond with this status code. The 304 response MUST NOT contain a 201 message-body, and thus is always terminated by the first empty line 202 after the header fields. 204 The response MUST include the following header fields: 206 o Date, unless its omission is required by Section 8.3.1 of [Part1] 208 If a clockless origin server obeys these rules, and proxies and 209 clients add their own Date to any response received without one (as 210 already specified by [RFC2068], Section 14.19), caches will operate 211 correctly. 213 o ETag and/or Content-Location, if the header would have been sent 214 in a 200 response to the same request 216 o Expires, Cache-Control, and/or Vary, if the field-value might 217 differ from that sent in any previous response for the same 218 variant 220 If the conditional GET used a strong cache validator (see Section 5), 221 the response SHOULD NOT include other entity-headers. Otherwise 222 (i.e., the conditional GET used a weak validator), the response MUST 223 NOT include other entity-headers; this prevents inconsistencies 224 between cached entity-bodies and updated headers. 226 If a 304 response indicates an entity not currently cached, then the 227 cache MUST disregard the response and repeat the request without the 228 conditional. 230 If a cache uses a received 304 response to update a cache entry, the 231 cache MUST update the entry to reflect any new field values given in 232 the response. 234 4.2. 412 Precondition Failed 236 The precondition given in one or more of the request-header fields 237 evaluated to false when it was tested on the server. This response 238 code allows the client to place preconditions on the current resource 239 metainformation (header field data) and thus prevent the requested 240 method from being applied to a resource other than the one intended. 242 5. Weak and Strong Validators 244 Since both origin servers and caches will compare two validators to 245 decide if they represent the same or different entities, one normally 246 would expect that if the entity (the entity-body or any entity- 247 headers) changes in any way, then the associated validator would 248 change as well. If this is true, then we call this validator a 249 "strong validator." 251 However, there might be cases when a server prefers to change the 252 validator only on semantically significant changes, and not when 253 insignificant aspects of the entity change. A validator that does 254 not always change when the resource changes is a "weak validator." 256 Entity tags are normally "strong validators," but the protocol 257 provides a mechanism to tag an entity tag as "weak." One can think 258 of a strong validator as one that changes whenever the bits of an 259 entity changes, while a weak value changes whenever the meaning of an 260 entity changes. Alternatively, one can think of a strong validator 261 as part of an identifier for a specific entity, while a weak 262 validator is part of an identifier for a set of semantically 263 equivalent entities. 265 Note: One example of a strong validator is an integer that is 266 incremented in stable storage every time an entity is changed. 268 An entity's modification time, if represented with one-second 269 resolution, could be a weak validator, since it is possible that 270 the resource might be modified twice during a single second. 272 Support for weak validators is optional. However, weak validators 273 allow for more efficient caching of equivalent objects; for 274 example, a hit counter on a site is probably good enough if it is 275 updated every few days or weeks, and any value during that period 276 is likely "good enough" to be equivalent. 278 A "use" of a validator is either when a client generates a request 279 and includes the validator in a validating header field, or when a 280 server compares two validators. 282 Strong validators are usable in any context. Weak validators are 283 only usable in contexts that do not depend on exact equality of an 284 entity. For example, either kind is usable for a conditional GET of 285 a full entity. However, only a strong validator is usable for a sub- 286 range retrieval, since otherwise the client might end up with an 287 internally inconsistent entity. 289 Clients MAY issue simple (non-subrange) GET requests with either weak 290 validators or strong validators. Clients MUST NOT use weak 291 validators in other forms of request. 293 The only function that HTTP/1.1 defines on validators is comparison. 294 There are two validator comparison functions, depending on whether 295 the comparison context allows the use of weak validators or not: 297 o The strong comparison function: in order to be considered equal, 298 both validators MUST be identical in every way, and both MUST NOT 299 be weak. 301 o The weak comparison function: in order to be considered equal, 302 both validators MUST be identical in every way, but either or both 303 of them MAY be tagged as "weak" without affecting the result. 305 An entity tag is strong unless it is explicitly tagged as weak. 306 Section 3 gives the syntax for entity tags. 308 A Last-Modified time, when used as a validator in a request, is 309 implicitly weak unless it is possible to deduce that it is strong, 310 using the following rules: 312 o The validator is being compared by an origin server to the actual 313 current validator for the entity and, 315 o That origin server reliably knows that the associated entity did 316 not change twice during the second covered by the presented 317 validator. 319 or 321 o The validator is about to be used by a client in an If-Modified- 322 Since or If-Unmodified-Since header, because the client has a 323 cache entry for the associated entity, and 325 o That cache entry includes a Date value, which gives the time when 326 the origin server sent the original response, and 328 o The presented Last-Modified time is at least 60 seconds before the 329 Date value. 331 or 333 o The validator is being compared by an intermediate cache to the 334 validator stored in its cache entry for the entity, and 336 o That cache entry includes a Date value, which gives the time when 337 the origin server sent the original response, and 339 o The presented Last-Modified time is at least 60 seconds before the 340 Date value. 342 This method relies on the fact that if two different responses were 343 sent by the origin server during the same second, but both had the 344 same Last-Modified time, then at least one of those responses would 345 have a Date value equal to its Last-Modified time. The arbitrary 60- 346 second limit guards against the possibility that the Date and Last- 347 Modified values are generated from different clocks, or at somewhat 348 different times during the preparation of the response. An 349 implementation MAY use a value larger than 60 seconds, if it is 350 believed that 60 seconds is too short. 352 If a client wishes to perform a sub-range retrieval on a value for 353 which it has only a Last-Modified time and no opaque validator, it 354 MAY do this only if the Last-Modified time is strong in the sense 355 described here. 357 A cache or origin server receiving a conditional request, other than 358 a full-body GET request, MUST use the strong comparison function to 359 evaluate the condition. 361 These rules allow HTTP/1.1 caches and clients to safely perform sub- 362 range retrievals on values that have been obtained from HTTP/1.0 363 servers. 365 6. Rules for When to Use Entity Tags and Last-Modified Dates 367 We adopt a set of rules and recommendations for origin servers, 368 clients, and caches regarding when various validator types ought to 369 be used, and for what purposes. 371 HTTP/1.1 origin servers: 373 o SHOULD send an entity tag validator unless it is not feasible to 374 generate one. 376 o MAY send a weak entity tag instead of a strong entity tag, if 377 performance considerations support the use of weak entity tags, or 378 if it is unfeasible to send a strong entity tag. 380 o SHOULD send a Last-Modified value if it is feasible to send one, 381 unless the risk of a breakdown in semantic transparency that could 382 result from using this date in an If-Modified-Since header would 383 lead to serious problems. 385 In other words, the preferred behavior for an HTTP/1.1 origin server 386 is to send both a strong entity tag and a Last-Modified value. 388 In order to be legal, a strong entity tag MUST change whenever the 389 associated entity value changes in any way. A weak entity tag SHOULD 390 change whenever the associated entity changes in a semantically 391 significant way. 393 Note: in order to provide semantically transparent caching, an 394 origin server must avoid reusing a specific strong entity tag 395 value for two different entities, or reusing a specific weak 396 entity tag value for two semantically different entities. Cache 397 entries might persist for arbitrarily long periods, regardless of 398 expiration times, so it might be inappropriate to expect that a 399 cache will never again attempt to validate an entry using a 400 validator that it obtained at some point in the past. 402 HTTP/1.1 clients: 404 o If an entity tag has been provided by the origin server, MUST use 405 that entity tag in any cache-conditional request (using If-Match 406 or If-None-Match). 408 o If only a Last-Modified value has been provided by the origin 409 server, SHOULD use that value in non-subrange cache-conditional 410 requests (using If-Modified-Since). 412 o If only a Last-Modified value has been provided by an HTTP/1.0 413 origin server, MAY use that value in subrange cache-conditional 414 requests (using If-Unmodified-Since:). The user agent SHOULD 415 provide a way to disable this, in case of difficulty. 417 o If both an entity tag and a Last-Modified value have been provided 418 by the origin server, SHOULD use both validators in cache- 419 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 420 caches to respond appropriately. 422 An HTTP/1.1 origin server, upon receiving a conditional request that 423 includes both a Last-Modified date (e.g., in an If-Modified-Since or 424 If-Unmodified-Since header field) and one or more entity tags (e.g., 425 in an If-Match, If-None-Match, or If-Range header field) as cache 426 validators, MUST NOT return a response status of 304 (Not Modified) 427 unless doing so is consistent with all of the conditional header 428 fields in the request. 430 An HTTP/1.1 caching proxy, upon receiving a conditional request that 431 includes both a Last-Modified date and one or more entity tags as 432 cache validators, MUST NOT return a locally cached response to the 433 client unless that cached response is consistent with all of the 434 conditional header fields in the request. 436 Note: The general principle behind these rules is that HTTP/1.1 437 servers and clients should transmit as much non-redundant 438 information as is available in their responses and requests. 439 HTTP/1.1 systems receiving this information will make the most 440 conservative assumptions about the validators they receive. 442 HTTP/1.0 clients and caches will ignore entity tags. Generally, 443 last-modified values received or used by these systems will 444 support transparent and efficient caching, and so HTTP/1.1 origin 445 servers should provide Last-Modified values. In those rare cases 446 where the use of a Last-Modified value as a validator by an 447 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 448 origin servers should not provide one. 450 7. Header Field Definitions 452 This section defines the syntax and semantics of HTTP/1.1 header 453 fields related to conditional requests. 455 For entity-header fields, both sender and recipient refer to either 456 the client or the server, depending on who sends and who receives the 457 entity. 459 7.1. ETag 461 The ETag response-header field provides the current value of the 462 entity tag for the requested variant. The headers used with entity 463 tags are described in Sections 7.2 and 7.4 of this document, and in 464 Section 6.3 of [Part5]. The entity tag MAY be used for comparison 465 with other entities from the same resource (see Section 5). 467 ETag = "ETag" ":" entity-tag 469 Examples: 471 ETag: "xyzzy" 472 ETag: W/"xyzzy" 473 ETag: "" 475 The ETag response-header field value, an entity tag, provides for an 476 "opaque" cache validator. This might allow more reliable validation 477 in situations where it is inconvenient to store modification dates, 478 where the one-second resolution of HTTP date values is not 479 sufficient, or where the origin server wishes to avoid certain 480 paradoxes that might arise from the use of modification dates. 482 The principle behind entity tags is that only the service author 483 knows the semantics of a resource well enough to select an 484 appropriate cache validation mechanism, and the specification of any 485 validator comparison function more complex than byte-equality would 486 open up a can of worms. Thus, comparisons of any other headers 487 (except Last-Modified, for compatibility with HTTP/1.0) are never 488 used for purposes of validating a cache entry. 490 7.2. If-Match 492 The If-Match request-header field is used with a method to make it 493 conditional. A client that has one or more entities previously 494 obtained from the resource can verify that one of those entities is 495 current by including a list of their associated entity tags in the 496 If-Match header field. Entity tags are defined in Section 3. The 497 purpose of this feature is to allow efficient updates of cached 498 information with a minimum amount of transaction overhead. It is 499 also used, on updating requests, to prevent inadvertent modification 500 of the wrong version of a resource. As a special case, the value "*" 501 matches any current entity of the resource. 503 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 505 If any of the entity tags match the entity tag of the entity that 506 would have been returned in the response to a similar GET request 507 (without the If-Match header) on that resource, or if "*" is given 508 and any current entity exists for that resource, then the server MAY 509 perform the requested method as if the If-Match header field did not 510 exist. 512 A server MUST use the strong comparison function (see Section 5) to 513 compare the entity tags in If-Match. 515 If none of the entity tags match, or if "*" is given and no current 516 entity exists, the server MUST NOT perform the requested method, and 517 MUST return a 412 (Precondition Failed) response. This behavior is 518 most useful when the client wants to prevent an updating method, such 519 as PUT, from modifying a resource that has changed since the client 520 last retrieved it. 522 If the request would, without the If-Match header field, result in 523 anything other than a 2xx or 412 status, then the If-Match header 524 MUST be ignored. 526 The meaning of "If-Match: *" is that the method SHOULD be performed 527 if the representation selected by the origin server (or by a cache, 528 possibly using the Vary mechanism, see Section 16.5 of [Part6]) 529 exists, and MUST NOT be performed if the representation does not 530 exist. 532 A request intended to update a resource (e.g., a PUT) MAY include an 533 If-Match header field to signal that the request method MUST NOT be 534 applied if the entity corresponding to the If-Match value (a single 535 entity tag) is no longer a representation of that resource. This 536 allows the user to indicate that they do not wish the request to be 537 successful if the resource has been changed without their knowledge. 539 Examples: 541 If-Match: "xyzzy" 542 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 543 If-Match: * 545 The result of a request having both an If-Match header field and 546 either an If-None-Match or an If-Modified-Since header fields is 547 undefined by this specification. 549 7.3. If-Modified-Since 551 The If-Modified-Since request-header field is used with a method to 552 make it conditional: if the requested variant has not been modified 553 since the time specified in this field, an entity will not be 554 returned from the server; instead, a 304 (Not Modified) response will 555 be returned without any message-body. 557 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 559 An example of the field is: 561 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 563 A GET method with an If-Modified-Since header and no Range header 564 requests that the identified entity be transferred only if it has 565 been modified since the date given by the If-Modified-Since header. 566 The algorithm for determining this includes the following cases: 568 1. If the request would normally result in anything other than a 200 569 (OK) status, or if the passed If-Modified-Since date is invalid, 570 the response is exactly the same as for a normal GET. A date 571 which is later than the server's current time is invalid. 573 2. If the variant has been modified since the If-Modified-Since 574 date, the response is exactly the same as for a normal GET. 576 3. If the variant has not been modified since a valid If-Modified- 577 Since date, the server SHOULD return a 304 (Not Modified) 578 response. 580 The purpose of this feature is to allow efficient updates of cached 581 information with a minimum amount of transaction overhead. 583 Note: The Range request-header field modifies the meaning of If- 584 Modified-Since; see Section 6.4 of [Part5] for full details. 586 Note: If-Modified-Since times are interpreted by the server, whose 587 clock might not be synchronized with the client. 589 Note: When handling an If-Modified-Since header field, some 590 servers will use an exact date comparison function, rather than a 591 less-than function, for deciding whether to send a 304 (Not 592 Modified) response. To get best results when sending an If- 593 Modified-Since header field for cache validation, clients are 594 advised to use the exact date string received in a previous Last- 595 Modified header field whenever possible. 597 Note: If a client uses an arbitrary date in the If-Modified-Since 598 header instead of a date taken from the Last-Modified header for 599 the same request, the client should be aware of the fact that this 600 date is interpreted in the server's understanding of time. The 601 client should consider unsynchronized clocks and rounding problems 602 due to the different encodings of time between the client and 603 server. This includes the possibility of race conditions if the 604 document has changed between the time it was first requested and 605 the If-Modified-Since date of a subsequent request, and the 606 possibility of clock-skew-related problems if the If-Modified- 607 Since date is derived from the client's clock without correction 608 to the server's clock. Corrections for different time bases 609 between client and server are at best approximate due to network 610 latency. 612 The result of a request having both an If-Modified-Since header field 613 and either an If-Match or an If-Unmodified-Since header fields is 614 undefined by this specification. 616 7.4. If-None-Match 618 The If-None-Match request-header field is used with a method to make 619 it conditional. A client that has one or more entities previously 620 obtained from the resource can verify that none of those entities is 621 current by including a list of their associated entity tags in the 622 If-None-Match header field. The purpose of this feature is to allow 623 efficient updates of cached information with a minimum amount of 624 transaction overhead. It is also used to prevent a method (e.g. 625 PUT) from inadvertently modifying an existing resource when the 626 client believes that the resource does not exist. 628 As a special case, the value "*" matches any current entity of the 629 resource. 631 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 633 If any of the entity tags match the entity tag of the entity that 634 would have been returned in the response to a similar GET request 635 (without the If-None-Match header) on that resource, or if "*" is 636 given and any current entity exists for that resource, then the 637 server MUST NOT perform the requested method, unless required to do 638 so because the resource's modification date fails to match that 639 supplied in an If-Modified-Since header field in the request. 640 Instead, if the request method was GET or HEAD, the server SHOULD 641 respond with a 304 (Not Modified) response, including the cache- 642 related header fields (particularly ETag) of one of the entities that 643 matched. For all other request methods, the server MUST respond with 644 a status of 412 (Precondition Failed). 646 See Section 5 for rules on how to determine if two entities tags 647 match. The weak comparison function can only be used with GET or 648 HEAD requests. 650 If none of the entity tags match, then the server MAY perform the 651 requested method as if the If-None-Match header field did not exist, 652 but MUST also ignore any If-Modified-Since header field(s) in the 653 request. That is, if no entity tags match, then the server MUST NOT 654 return a 304 (Not Modified) response. 656 If the request would, without the If-None-Match header field, result 657 in anything other than a 2xx or 304 status, then the If-None-Match 658 header MUST be ignored. (See Section 6 for a discussion of server 659 behavior when both If-Modified-Since and If-None-Match appear in the 660 same request.) 662 The meaning of "If-None-Match: *" is that the method MUST NOT be 663 performed if the representation selected by the origin server (or by 664 a cache, possibly using the Vary mechanism, see Section 16.5 of 665 [Part6]) exists, and SHOULD be performed if the representation does 666 not exist. This feature is intended to be useful in preventing races 667 between PUT operations. 669 Examples: 671 If-None-Match: "xyzzy" 672 If-None-Match: W/"xyzzy" 673 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 674 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 675 If-None-Match: * 677 The result of a request having both an If-None-Match header field and 678 either an If-Match or an If-Unmodified-Since header fields is 679 undefined by this specification. 681 7.5. If-Unmodified-Since 683 The If-Unmodified-Since request-header field is used with a method to 684 make it conditional. If the requested resource has not been modified 685 since the time specified in this field, the server SHOULD perform the 686 requested operation as if the If-Unmodified-Since header were not 687 present. 689 If the requested variant has been modified since the specified time, 690 the server MUST NOT perform the requested operation, and MUST return 691 a 412 (Precondition Failed). 693 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 695 An example of the field is: 697 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 699 If the request normally (i.e., without the If-Unmodified-Since 700 header) would result in anything other than a 2xx or 412 status, the 701 If-Unmodified-Since header SHOULD be ignored. 703 If the specified date is invalid, the header is ignored. 705 The result of a request having both an If-Unmodified-Since header 706 field and either an If-None-Match or an If-Modified-Since header 707 fields is undefined by this specification. 709 7.6. Last-Modified 711 The Last-Modified entity-header field indicates the date and time at 712 which the origin server believes the variant was last modified. 714 Last-Modified = "Last-Modified" ":" HTTP-date 716 An example of its use is 718 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 720 The exact meaning of this header field depends on the implementation 721 of the origin server and the nature of the original resource. For 722 files, it may be just the file system last-modified time. For 723 entities with dynamically included parts, it may be the most recent 724 of the set of last-modify times for its component parts. For 725 database gateways, it may be the last-update time stamp of the 726 record. For virtual objects, it may be the last time the internal 727 state changed. 729 An origin server MUST NOT send a Last-Modified date which is later 730 than the server's time of message origination. In such cases, where 731 the resource's last modification would indicate some time in the 732 future, the server MUST replace that date with the message 733 origination date. 735 An origin server SHOULD obtain the Last-Modified value of the entity 736 as close as possible to the time that it generates the Date value of 737 its response. This allows a recipient to make an accurate assessment 738 of the entity's modification time, especially if the entity changes 739 near the time that the response is generated. 741 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 743 The Last-Modified entity-header field value is often used as a cache 744 validator. In simple terms, a cache entry is considered to be valid 745 if the entity has not been modified since the Last-Modified value. 747 8. IANA Considerations 749 [[anchor2: TBD.]] 751 9. Security Considerations 753 No additional security considerations have been identified beyond 754 those applicable to HTTP in general [Part1]. 756 10. Acknowledgments 758 11. References 760 11.1. Normative References 762 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 763 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 764 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 765 and Message Parsing", draft-ietf-httpbis-p1-messaging-02 766 (work in progress), February 2008. 768 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 769 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 770 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 771 Partial Responses", draft-ietf-httpbis-p5-range-02 (work 772 in progress), February 2008. 774 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 775 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 776 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 777 draft-ietf-httpbis-p6-cache-02 (work in progress), 778 February 2008. 780 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 781 Requirement Levels", BCP 14, RFC 2119, March 1997. 783 11.2. Informative References 785 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 786 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 787 RFC 2068, January 1997. 789 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 790 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 791 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 793 Appendix A. Compatibility with Previous Versions 795 A.1. Changes from RFC 2616 797 Appendix B. Change Log (to be removed by RFC Editor before publication) 799 B.1. Since RFC2616 801 Extracted relevant partitions from [RFC2616]. 803 B.2. Since draft-ietf-httpbis-p4-conditional-00 805 Closed issues: 807 o : "Normative 808 and Informative references" 810 Other changes: 812 o Move definitions of 304 and 412 condition codes from Part2. 814 B.3. Since draft-ietf-httpbis-p4-conditional-01 816 Ongoing work on ABNF conversion 817 (): 819 o Add explicit references to BNF syntax and rules imported from 820 other parts of the specification. 822 Index 824 3 825 304 Not Modified (status code) 5 827 4 828 412 Precondition Failed (status code) 6 830 E 831 ETag header 11 833 G 834 Grammar 835 entity-tag 5 836 ETag 11 837 If-Match 12 838 If-Modified-Since 13 839 If-None-Match 14 840 If-Unmodified-Since 16 841 Last-Modified 16 842 opaque-tag 5 843 weak 5 845 H 846 Headers 847 ETag 11 848 If-Match 12 849 If-Modified-Since 13 850 If-None-Match 14 851 If-Unmodified-Since 16 852 Last-Modified 16 854 I 855 If-Match header 12 856 If-Modified-Since header 13 857 If-None-Match header 14 858 If-Unmodified-Since header 16 860 L 861 Last-Modified header 16 863 S 864 Status Codes 865 304 Not Modified 5 866 412 Precondition Failed 6 868 Authors' Addresses 870 Roy T. Fielding (editor) 871 Day Software 872 23 Corporate Plaza DR, Suite 280 873 Newport Beach, CA 92660 874 USA 876 Phone: +1-949-706-5300 877 Fax: +1-949-706-5305 878 Email: fielding@gbiv.com 879 URI: http://roy.gbiv.com/ 881 Jim Gettys 882 One Laptop per Child 883 21 Oak Knoll Road 884 Carlisle, MA 01741 885 USA 887 Email: jg@laptop.org 888 URI: http://www.laptop.org/ 890 Jeffrey C. Mogul 891 Hewlett-Packard Company 892 HP Labs, Large Scale Systems Group 893 1501 Page Mill Road, MS 1177 894 Palo Alto, CA 94304 895 USA 897 Email: JeffMogul@acm.org 899 Henrik Frystyk Nielsen 900 Microsoft Corporation 901 1 Microsoft Way 902 Redmond, WA 98052 903 USA 905 Email: henrikn@microsoft.com 906 Larry Masinter 907 Adobe Systems, Incorporated 908 345 Park Ave 909 San Jose, CA 95110 910 USA 912 Email: LMM@acm.org 913 URI: http://larry.masinter.net/ 915 Paul J. Leach 916 Microsoft Corporation 917 1 Microsoft Way 918 Redmond, WA 98052 920 Email: paulle@microsoft.com 922 Tim Berners-Lee 923 World Wide Web Consortium 924 MIT Computer Science and Artificial Intelligence Laboratory 925 The Stata Center, Building 32 926 32 Vassar Street 927 Cambridge, MA 02139 928 USA 930 Email: timbl@w3.org 931 URI: http://www.w3.org/People/Berners-Lee/ 933 Yves Lafon (editor) 934 World Wide Web Consortium 935 W3C / ERCIM 936 2004, rte des Lucioles 937 Sophia-Antipolis, AM 06902 938 France 940 Email: ylafon@w3.org 941 URI: http://www.raubacapeu.net/people/yves/ 942 Julian F. Reschke (editor) 943 greenbytes GmbH 944 Hafenweg 16 945 Muenster, NW 48155 946 Germany 948 Phone: +49 251 2807760 949 Fax: +49 251 2807761 950 Email: julian.reschke@greenbytes.de 951 URI: http://greenbytes.de/tech/webdav/ 953 Full Copyright Statement 955 Copyright (C) The IETF Trust (2008). 957 This document is subject to the rights, licenses and restrictions 958 contained in BCP 78, and except as set forth therein, the authors 959 retain all their rights. 961 This document and the information contained herein are provided on an 962 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 963 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 964 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 965 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 966 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 967 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 969 Intellectual Property 971 The IETF takes no position regarding the validity or scope of any 972 Intellectual Property Rights or other rights that might be claimed to 973 pertain to the implementation or use of the technology described in 974 this document or the extent to which any license under such rights 975 might or might not be available; nor does it represent that it has 976 made any independent effort to identify any such rights. Information 977 on the procedures with respect to rights in RFC documents can be 978 found in BCP 78 and BCP 79. 980 Copies of IPR disclosures made to the IETF Secretariat and any 981 assurances of licenses to be made available, or the result of an 982 attempt made to obtain a general license or permission for the use of 983 such proprietary rights by implementers or users of this 984 specification can be obtained from the IETF on-line IPR repository at 985 http://www.ietf.org/ipr. 987 The IETF invites any interested party to bring to its attention any 988 copyrights, patents or patent applications, or other proprietary 989 rights that may cover technology that may be required to implement 990 this standard. Please address the information to the IETF at 991 ietf-ipr@ietf.org. 993 Acknowledgment 995 Funding for the RFC Editor function is provided by the IETF 996 Administrative Support Activity (IASA).