idnits 2.17.1 draft-ietf-httpbis-p4-conditional-04.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 1015. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1026. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1033. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1039. 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 (August 29, 2008) is 5719 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-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-04 -- 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: March 2, 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 August 29, 2008 22 HTTP/1.1, part 4: Conditional Requests 23 draft-ietf-httpbis-p4-conditional-04 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 March 2, 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.4. 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 . . . . . . . . . . . . . . . . . . . 17 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 . . . . . . . . . . . . . . . . . . 18 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 . . . . . . . . 19 105 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 107 Intellectual Property and Copyright Statements . . . . . . . . . . 24 109 1. Introduction 111 This document defines HTTP/1.1 response metadata for indicating 112 potential changes to payload content, including modification time 113 stamps and opaque entity-tags, and the HTTP conditional request 114 mechanisms that allow preconditions to be placed on a request method. 115 Conditional GET requests allow for efficient cache updates. Other 116 conditional request methods are used to protect against overwriting 117 or misunderstanding the state of a resource that has been changed 118 unbeknownst to the requesting client. 120 This document is currently disorganized in order to minimize the 121 changes between drafts and enable reviewers to see the smaller errata 122 changes. The next draft will reorganize the sections to better 123 reflect the content. In particular, the sections on resource 124 metadata will be discussed first and then followed by each 125 conditional request-header, concluding with a definition of 126 precedence and the expectation of ordering strong validator checks 127 before weak validator checks. It is likely that more content from 128 [Part6] will migrate to this part, where appropriate. The current 129 mess reflects how widely dispersed these topics and associated 130 requirements had become in [RFC2616]. 132 1.1. Requirements 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 136 document are to be interpreted as described in [RFC2119]. 138 An implementation is not compliant if it fails to satisfy one or more 139 of the MUST or REQUIRED level requirements for the protocols it 140 implements. An implementation that satisfies all the MUST or 141 REQUIRED level and all the SHOULD level requirements for its 142 protocols is said to be "unconditionally compliant"; one that 143 satisfies all the MUST level requirements but not all the SHOULD 144 level requirements for its protocols is said to be "conditionally 145 compliant." 147 2. Notational Conventions and Generic Grammar 149 This specification uses the ABNF syntax defined in Section 2.1 of 150 [Part1] and the core rules defined in Section 2.2 of [Part1]: 151 [[abnf.dep: ABNF syntax and basic rules will be adopted from RFC 152 5234, see .]] 154 quoted-string = 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." 251 Entity tags are normally "strong validators," but the protocol 252 provides a mechanism to tag an entity tag as "weak." One can think 253 of a strong validator as one that changes whenever the bits of an 254 entity changes, while a weak value changes whenever the meaning of an 255 entity changes. Alternatively, one can think of a strong validator 256 as part of an identifier for a specific entity, while a weak 257 validator is part of an identifier for a set of semantically 258 equivalent entities. 260 Note: One example of a strong validator is an integer that is 261 incremented in stable storage every time an entity is changed. 263 An entity's modification time, if represented with one-second 264 resolution, could be a weak validator, since it is possible that 265 the resource might be modified twice during a single second. 267 Support for weak validators is optional. However, weak validators 268 allow for more efficient caching of equivalent objects; for 269 example, a hit counter on a site is probably good enough if it is 270 updated every few days or weeks, and any value during that period 271 is likely "good enough" to be equivalent. 273 A "use" of a validator is either when a client generates a request 274 and includes the validator in a validating header field, or when a 275 server compares two validators. 277 Strong validators are usable in any context. Weak validators are 278 only usable in contexts that do not depend on exact equality of an 279 entity. For example, either kind is usable for a conditional GET of 280 a full entity. However, only a strong validator is usable for a sub- 281 range retrieval, since otherwise the client might end up with an 282 internally inconsistent entity. 284 Clients MUST NOT use weak validators in range requests ([Part5]). 286 The only function that HTTP/1.1 defines on validators is comparison. 287 There are two validator comparison functions, depending on whether 288 the comparison context allows the use of weak validators or not: 290 o The strong comparison function: in order to be considered equal, 291 both opaque-tags MUST be identical character-by-character, and 292 both MUST NOT be weak. 294 o The weak comparison function: in order to be considered equal, 295 both opaque-tags MUST be identical character-by-character. 297 The example below shows the results for a set of entity tag pairs, 298 and both the weak and strong comparison function results: 300 +--------+--------+-------------------+-----------------+ 301 | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | 302 +--------+--------+-------------------+-----------------+ 303 | W/"1" | W/"1" | no match | match | 304 | W/"1" | W/"2" | no match | no match | 305 | W/"1" | "1" | no match | match | 306 | "1" | "1" | match | match | 307 +--------+--------+-------------------+-----------------+ 309 An entity tag is strong unless it is explicitly tagged as weak. 310 Section 3 gives the syntax for entity tags. 312 A Last-Modified time, when used as a validator in a request, is 313 implicitly weak unless it is possible to deduce that it is strong, 314 using the following rules: 316 o The validator is being compared by an origin server to the actual 317 current validator for the entity and, 319 o That origin server reliably knows that the associated entity did 320 not change twice during the second covered by the presented 321 validator. 323 or 325 o The validator is about to be used by a client in an If-Modified- 326 Since or If-Unmodified-Since header, because the client has a 327 cache entry for the associated entity, and 329 o That cache entry includes a Date value, which gives the time when 330 the origin server sent the original response, and 332 o The presented Last-Modified time is at least 60 seconds before the 333 Date value. 335 or 337 o The validator is being compared by an intermediate cache to the 338 validator stored in its cache entry for the entity, and 340 o That cache entry includes a Date value, which gives the time when 341 the origin server sent the original response, and 343 o The presented Last-Modified time is at least 60 seconds before the 344 Date value. 346 This method relies on the fact that if two different responses were 347 sent by the origin server during the same second, but both had the 348 same Last-Modified time, then at least one of those responses would 349 have a Date value equal to its Last-Modified time. The arbitrary 60- 350 second limit guards against the possibility that the Date and Last- 351 Modified values are generated from different clocks, or at somewhat 352 different times during the preparation of the response. An 353 implementation MAY use a value larger than 60 seconds, if it is 354 believed that 60 seconds is too short. 356 If a client wishes to perform a sub-range retrieval on a value for 357 which it has only a Last-Modified time and no opaque validator, it 358 MAY do this only if the Last-Modified time is strong in the sense 359 described here. 361 A cache or origin server receiving a conditional range request 362 ([Part5]) MUST use the strong comparison function to evaluate the 363 condition. 365 These rules allow HTTP/1.1 caches and clients to safely perform sub- 366 range retrievals on values that have been obtained from HTTP/1.0 367 servers. 369 6. Rules for When to Use Entity Tags and Last-Modified Dates 371 We adopt a set of rules and recommendations for origin servers, 372 clients, and caches regarding when various validator types ought to 373 be used, and for what purposes. 375 HTTP/1.1 origin servers: 377 o SHOULD send an entity tag validator unless it is not feasible to 378 generate one. 380 o MAY send a weak entity tag instead of a strong entity tag, if 381 performance considerations support the use of weak entity tags, or 382 if it is unfeasible to send a strong entity tag. 384 o SHOULD send a Last-Modified value if it is feasible to send one, 385 unless the risk of a breakdown in semantic transparency that could 386 result from using this date in an If-Modified-Since header would 387 lead to serious problems. 389 In other words, the preferred behavior for an HTTP/1.1 origin server 390 is to send both a strong entity tag and a Last-Modified value. 392 In order to be legal, a strong entity tag MUST change whenever the 393 associated entity changes in any way. A weak entity tag SHOULD 394 change whenever the associated entity changes in a semantically 395 significant way. 397 Note: in order to provide semantically transparent caching, an 398 origin server must avoid reusing a specific strong entity tag 399 value for two different entities, or reusing a specific weak 400 entity tag value for two semantically different entities. Cache 401 entries might persist for arbitrarily long periods, regardless of 402 expiration times, so it might be inappropriate to expect that a 403 cache will never again attempt to validate an entry using a 404 validator that it obtained at some point in the past. 406 HTTP/1.1 clients: 408 o If an entity tag has been provided by the origin server, MUST use 409 that entity tag in any cache-conditional request (using If-Match 410 or If-None-Match). 412 o If only a Last-Modified value has been provided by the origin 413 server, SHOULD use that value in non-subrange cache-conditional 414 requests (using If-Modified-Since). 416 o If only a Last-Modified value has been provided by an HTTP/1.0 417 origin server, MAY use that value in subrange cache-conditional 418 requests (using If-Unmodified-Since:). The user agent SHOULD 419 provide a way to disable this, in case of difficulty. 421 o If both an entity tag and a Last-Modified value have been provided 422 by the origin server, SHOULD use both validators in cache- 423 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 424 caches to respond appropriately. 426 An HTTP/1.1 origin server, upon receiving a conditional request that 427 includes both a Last-Modified date (e.g., in an If-Modified-Since or 428 If-Unmodified-Since header field) and one or more entity tags (e.g., 429 in an If-Match, If-None-Match, or If-Range header field) as cache 430 validators, MUST NOT return a response status of 304 (Not Modified) 431 unless doing so is consistent with all of the conditional header 432 fields in the request. 434 An HTTP/1.1 caching proxy, upon receiving a conditional request that 435 includes both a Last-Modified date and one or more entity tags as 436 cache validators, MUST NOT return a locally cached response to the 437 client unless that cached response is consistent with all of the 438 conditional header fields in the request. 440 Note: The general principle behind these rules is that HTTP/1.1 441 servers and clients should transmit as much non-redundant 442 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 ETag response-header field provides the current value of the 466 entity tag for the requested variant. The headers used with entity 467 tags are described in Sections 7.2 and 7.4 of this document, and in 468 Section 6.3 of [Part5]. The entity tag MAY be used for comparison 469 with other entities from the same resource (see Section 5). 471 ETag = "ETag" ":" entity-tag 473 Examples: 475 ETag: "xyzzy" 476 ETag: W/"xyzzy" 477 ETag: "" 479 The ETag response-header field value, an entity tag, provides for an 480 "opaque" cache validator. This might allow more reliable validation 481 in situations where it is inconvenient to store modification dates, 482 where the one-second resolution of HTTP date values is not 483 sufficient, or where the origin server wishes to avoid certain 484 paradoxes that might arise from the use of modification dates. 486 The principle behind entity tags is that only the service author 487 knows the semantics of a resource well enough to select an 488 appropriate cache validation mechanism, and the specification of any 489 validator comparison function more complex than byte-equality would 490 open up a can of worms. Thus, comparisons of any other headers 491 (except Last-Modified, for compatibility with HTTP/1.0) are never 492 used for purposes of validating a cache entry. 494 7.2. If-Match 496 The If-Match request-header field is used with a method to make it 497 conditional. A client that has one or more entities previously 498 obtained from the resource can verify that one of those entities is 499 current by including a list of their associated entity tags in the 500 If-Match header field. Entity tags are defined in Section 3. The 501 purpose of this feature is to allow efficient updates of cached 502 information with a minimum amount of transaction overhead. It is 503 also used, on updating requests, to prevent inadvertent modification 504 of the wrong version of a resource. As a special case, the value "*" 505 matches any current entity of the resource. 507 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 509 If any of the entity tags match the entity tag of the entity that 510 would have been returned in the response to a similar GET request 511 (without the If-Match header) on that resource, or if "*" is given 512 and any current entity exists for that resource, then the server MAY 513 perform the requested method as if the If-Match header field did not 514 exist. 516 A server MUST use the strong comparison function (see Section 5) to 517 compare the entity tags in If-Match. 519 If none of the entity tags match, or if "*" is given and no current 520 entity exists, the server MUST NOT perform the requested method, and 521 MUST return a 412 (Precondition Failed) response. This behavior is 522 most useful when the client wants to prevent an updating method, such 523 as PUT, from modifying a resource that has changed since the client 524 last retrieved it. 526 If the request would, without the If-Match header field, result in 527 anything other than a 2xx or 412 status, then the If-Match header 528 MUST be ignored. 530 The meaning of "If-Match: *" is that the method SHOULD be performed 531 if the representation selected by the origin server (or by a cache, 532 possibly using the Vary mechanism, see Section 16.5 of [Part6]) 533 exists, and MUST NOT be performed if the representation does not 534 exist. 536 A request intended to update a resource (e.g., a PUT) MAY include an 537 If-Match header field to signal that the request method MUST NOT be 538 applied if the entity corresponding to the If-Match value (a single 539 entity tag) is no longer a representation of that resource. This 540 allows the user to indicate that they do not wish the request to be 541 successful if the resource has been changed without their knowledge. 542 Examples: 544 If-Match: "xyzzy" 545 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 546 If-Match: * 548 The result of a request having both an If-Match header field and 549 either an If-None-Match or an If-Modified-Since header fields is 550 undefined by this specification. 552 7.3. If-Modified-Since 554 The If-Modified-Since request-header field is used with a method to 555 make it conditional: if the requested variant has not been modified 556 since the time specified in this field, an entity will not be 557 returned from the server; instead, a 304 (Not Modified) response will 558 be returned without any message-body. 560 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 562 An example of the field is: 564 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 566 A GET method with an If-Modified-Since header and no Range header 567 requests that the identified entity be transferred only if it has 568 been modified since the date given by the If-Modified-Since header. 569 The algorithm for determining this includes the following cases: 571 1. If the request would normally result in anything other than a 200 572 (OK) status, or if the passed If-Modified-Since date is invalid, 573 the response is exactly the same as for a normal GET. A date 574 which is later than the server's current time is invalid. 576 2. If the variant has been modified since the If-Modified-Since 577 date, the response is exactly the same as for a normal GET. 579 3. If the variant has not been modified since a valid If-Modified- 580 Since date, the server SHOULD return a 304 (Not Modified) 581 response. 583 The purpose of this feature is to allow efficient updates of cached 584 information with a minimum amount of transaction overhead. 586 Note: The Range request-header field modifies the meaning of If- 587 Modified-Since; see Section 6.4 of [Part5] for full details. 589 Note: If-Modified-Since times are interpreted by the server, whose 590 clock might not be synchronized with the client. 592 Note: When handling an If-Modified-Since header field, some 593 servers will use an exact date comparison function, rather than a 594 less-than function, for deciding whether to send a 304 (Not 595 Modified) response. To get best results when sending an If- 596 Modified-Since header field for cache validation, clients are 597 advised to use the exact date string received in a previous Last- 598 Modified header field whenever possible. 600 Note: If a client uses an arbitrary date in the If-Modified-Since 601 header instead of a date taken from the Last-Modified header for 602 the same request, the client should be aware of the fact that this 603 date is interpreted in the server's understanding of time. The 604 client should consider unsynchronized clocks and rounding problems 605 due to the different encodings of time between the client and 606 server. This includes the possibility of race conditions if the 607 document has changed between the time it was first requested and 608 the If-Modified-Since date of a subsequent request, and the 609 possibility of clock-skew-related problems if the If-Modified- 610 Since date is derived from the client's clock without correction 611 to the server's clock. Corrections for different time bases 612 between client and server are at best approximate due to network 613 latency. 615 The result of a request having both an If-Modified-Since header field 616 and either an If-Match or an If-Unmodified-Since header fields is 617 undefined by this specification. 619 7.4. If-None-Match 621 The If-None-Match request-header field is used with a method to make 622 it conditional. A client that has one or more entities previously 623 obtained from the resource can verify that none of those entities is 624 current by including a list of their associated entity tags in the 625 If-None-Match header field. The purpose of this feature is to allow 626 efficient updates of cached information with a minimum amount of 627 transaction overhead. It is also used to prevent a method (e.g. 628 PUT) from inadvertently modifying an existing resource when the 629 client believes that the resource does not exist. 631 As a special case, the value "*" matches any current entity of the 632 resource. 634 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 636 If any of the entity tags match the entity tag of the entity that 637 would have been returned in the response to a similar GET request 638 (without the If-None-Match header) on that resource, or if "*" is 639 given and any current entity exists for that resource, then the 640 server MUST NOT perform the requested method, unless required to do 641 so because the resource's modification date fails to match that 642 supplied in an If-Modified-Since header field in the request. 643 Instead, if the request method was GET or HEAD, the server SHOULD 644 respond with a 304 (Not Modified) response, including the cache- 645 related header fields (particularly ETag) of one of the entities that 646 matched. For all other request methods, the server MUST respond with 647 a status of 412 (Precondition Failed). 649 See Section 5 for rules on how to determine if two entity tags match. 651 If none of the entity tags match, then the server MAY perform the 652 requested method as if the If-None-Match header field did not exist, 653 but MUST also ignore any If-Modified-Since header field(s) in the 654 request. That is, if no entity tags match, then the server MUST NOT 655 return a 304 (Not Modified) response. 657 If the request would, without the If-None-Match header field, result 658 in anything other than a 2xx or 304 status, then the If-None-Match 659 header MUST be ignored. (See Section 6 for a discussion of server 660 behavior when both If-Modified-Since and If-None-Match appear in the 661 same request.) 663 The meaning of "If-None-Match: *" is that the method MUST NOT be 664 performed if the representation selected by the origin server (or by 665 a cache, possibly using the Vary mechanism, see Section 16.5 of 666 [Part6]) exists, and SHOULD be performed if the representation does 667 not exist. This feature is intended to be useful in preventing races 668 between PUT operations. 670 Examples: 672 If-None-Match: "xyzzy" 673 If-None-Match: W/"xyzzy" 674 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 675 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 676 If-None-Match: * 678 The result of a request having both an If-None-Match header field and 679 either an If-Match or an If-Unmodified-Since header fields is 680 undefined by this specification. 682 7.5. If-Unmodified-Since 684 The If-Unmodified-Since request-header field is used with a method to 685 make it conditional. If the requested resource has not been modified 686 since the time specified in this field, the server SHOULD perform the 687 requested operation as if the If-Unmodified-Since header were not 688 present. 690 If the requested variant has been modified since the specified time, 691 the server MUST NOT perform the requested operation, and MUST return 692 a 412 (Precondition Failed). 694 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 696 An example of the field is: 698 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 700 If the request normally (i.e., without the If-Unmodified-Since 701 header) would result in anything other than a 2xx or 412 status, the 702 If-Unmodified-Since header SHOULD be ignored. 704 If the specified date is invalid, the header is ignored. 706 The result of a request having both an If-Unmodified-Since header 707 field and either an If-None-Match or an If-Modified-Since header 708 fields is undefined by this specification. 710 7.6. Last-Modified 712 The Last-Modified entity-header field indicates the date and time at 713 which the origin server believes the variant was last modified. 715 Last-Modified = "Last-Modified" ":" HTTP-date 717 An example of its use is 719 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 721 The exact meaning of this header field depends on the implementation 722 of the origin server and the nature of the original resource. For 723 files, it may be just the file system last-modified time. For 724 entities with dynamically included parts, it may be the most recent 725 of the set of last-modify times for its component parts. For 726 database gateways, it may be the last-update time stamp of the 727 record. For virtual objects, it may be the last time the internal 728 state changed. 730 An origin server MUST NOT send a Last-Modified date which is later 731 than the server's time of message origination. In such cases, where 732 the resource's last modification would indicate some time in the 733 future, the server MUST replace that date with the message 734 origination date. 736 An origin server SHOULD obtain the Last-Modified value of the entity 737 as close as possible to the time that it generates the Date value of 738 its response. This allows a recipient to make an accurate assessment 739 of the entity's modification time, especially if the entity changes 740 near the time that the response is generated. 742 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 744 The Last-Modified entity-header field value is often used as a cache 745 validator. In simple terms, a cache entry is considered to be valid 746 if the entity has not been modified since the Last-Modified value. 748 8. IANA Considerations 750 8.1. Message Header Registration 752 The Message Header Registry located at should be 754 updated with the permanent registrations below (see [RFC3864]): 756 +---------------------+----------+----------+-------------+ 757 | Header Field Name | Protocol | Status | Reference | 758 +---------------------+----------+----------+-------------+ 759 | ETag | http | standard | Section 7.1 | 760 | If-Match | http | standard | Section 7.2 | 761 | If-Modified-Since | http | standard | Section 7.3 | 762 | If-None-Match | http | standard | Section 7.4 | 763 | If-Unmodified-Since | http | standard | Section 7.5 | 764 | Last-Modified | http | standard | Section 7.6 | 765 +---------------------+----------+----------+-------------+ 767 The change controller is: "IETF (iesg@ietf.org) - Internet 768 Engineering Task Force". 770 9. Security Considerations 772 No additional security considerations have been identified beyond 773 those applicable to HTTP in general [Part1]. 775 10. Acknowledgments 777 11. References 779 11.1. Normative References 781 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 782 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 783 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 784 and Message Parsing", draft-ietf-httpbis-p1-messaging-04 785 (work in progress), August 2008. 787 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 788 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 789 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 790 Partial Responses", draft-ietf-httpbis-p5-range-04 (work 791 in progress), August 2008. 793 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 794 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 795 and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", 796 draft-ietf-httpbis-p6-cache-04 (work in progress), 797 August 2008. 799 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 800 Requirement Levels", BCP 14, RFC 2119, March 1997. 802 11.2. Informative References 804 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 805 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 806 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 808 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 809 Procedures for Message Header Fields", BCP 90, RFC 3864, 810 September 2004. 812 Appendix A. Compatibility with Previous Versions 814 A.1. Changes from RFC 2616 816 Allow weak entity tags in all requests except range requests 817 (Sections 5 and 7.4). 819 Appendix B. Change Log (to be removed by RFC Editor before publication) 821 B.1. Since RFC2616 823 Extracted relevant partitions from [RFC2616]. 825 B.2. Since draft-ietf-httpbis-p4-conditional-00 827 Closed issues: 829 o : "Normative 830 and Informative references" 832 Other changes: 834 o Move definitions of 304 and 412 condition codes from Part2. 836 B.3. Since draft-ietf-httpbis-p4-conditional-01 838 Ongoing work on ABNF conversion 839 (): 841 o Add explicit references to BNF syntax and rules imported from 842 other parts of the specification. 844 B.4. Since draft-ietf-httpbis-p4-conditional-02 846 Closed issues: 848 o : "Weak 849 ETags on non-GET requests" 851 Ongoing work on IANA Message Header Registration 852 (): 854 o Reference RFC 3984, and update header registrations for headers 855 defined in this document. 857 B.5. Since draft-ietf-httpbis-p4-conditional-03 859 Closed issues: 861 o : "Examples 862 for ETag matching" 864 o : "'entity 865 value' undefined" 867 o : "bogus 868 2068 Date header reference" 870 Index 872 3 873 304 Not Modified (status code) 5 875 4 876 412 Precondition Failed (status code) 6 878 E 879 ETag header 11 881 G 882 Grammar 883 entity-tag 5 884 ETag 11 885 If-Match 12 886 If-Modified-Since 13 887 If-None-Match 15 888 If-Unmodified-Since 16 889 Last-Modified 16 890 opaque-tag 5 891 weak 5 893 H 894 Headers 895 ETag 11 896 If-Match 12 897 If-Modified-Since 13 898 If-None-Match 14 899 If-Unmodified-Since 16 900 Last-Modified 16 902 I 903 If-Match header 12 904 If-Modified-Since header 13 905 If-None-Match header 14 906 If-Unmodified-Since header 16 908 L 909 Last-Modified header 16 911 S 912 Status Codes 913 304 Not Modified 5 914 412 Precondition Failed 6 916 Authors' Addresses 918 Roy T. Fielding (editor) 919 Day Software 920 23 Corporate Plaza DR, Suite 280 921 Newport Beach, CA 92660 922 USA 924 Phone: +1-949-706-5300 925 Fax: +1-949-706-5305 926 Email: fielding@gbiv.com 927 URI: http://roy.gbiv.com/ 929 Jim Gettys 930 One Laptop per Child 931 21 Oak Knoll Road 932 Carlisle, MA 01741 933 USA 935 Email: jg@laptop.org 936 URI: http://www.laptop.org/ 938 Jeffrey C. Mogul 939 Hewlett-Packard Company 940 HP Labs, Large Scale Systems Group 941 1501 Page Mill Road, MS 1177 942 Palo Alto, CA 94304 943 USA 945 Email: JeffMogul@acm.org 947 Henrik Frystyk Nielsen 948 Microsoft Corporation 949 1 Microsoft Way 950 Redmond, WA 98052 951 USA 953 Email: henrikn@microsoft.com 954 Larry Masinter 955 Adobe Systems, Incorporated 956 345 Park Ave 957 San Jose, CA 95110 958 USA 960 Email: LMM@acm.org 961 URI: http://larry.masinter.net/ 963 Paul J. Leach 964 Microsoft Corporation 965 1 Microsoft Way 966 Redmond, WA 98052 968 Email: paulle@microsoft.com 970 Tim Berners-Lee 971 World Wide Web Consortium 972 MIT Computer Science and Artificial Intelligence Laboratory 973 The Stata Center, Building 32 974 32 Vassar Street 975 Cambridge, MA 02139 976 USA 978 Email: timbl@w3.org 979 URI: http://www.w3.org/People/Berners-Lee/ 981 Yves Lafon (editor) 982 World Wide Web Consortium 983 W3C / ERCIM 984 2004, rte des Lucioles 985 Sophia-Antipolis, AM 06902 986 France 988 Email: ylafon@w3.org 989 URI: http://www.raubacapeu.net/people/yves/ 990 Julian F. Reschke (editor) 991 greenbytes GmbH 992 Hafenweg 16 993 Muenster, NW 48155 994 Germany 996 Phone: +49 251 2807760 997 Fax: +49 251 2807761 998 Email: julian.reschke@greenbytes.de 999 URI: http://greenbytes.de/tech/webdav/ 1001 Full Copyright Statement 1003 Copyright (C) The IETF Trust (2008). 1005 This document is subject to the rights, licenses and restrictions 1006 contained in BCP 78, and except as set forth therein, the authors 1007 retain all their rights. 1009 This document and the information contained herein are provided on an 1010 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1011 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1012 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1013 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1014 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1015 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1017 Intellectual Property 1019 The IETF takes no position regarding the validity or scope of any 1020 Intellectual Property Rights or other rights that might be claimed to 1021 pertain to the implementation or use of the technology described in 1022 this document or the extent to which any license under such rights 1023 might or might not be available; nor does it represent that it has 1024 made any independent effort to identify any such rights. Information 1025 on the procedures with respect to rights in RFC documents can be 1026 found in BCP 78 and BCP 79. 1028 Copies of IPR disclosures made to the IETF Secretariat and any 1029 assurances of licenses to be made available, or the result of an 1030 attempt made to obtain a general license or permission for the use of 1031 such proprietary rights by implementers or users of this 1032 specification can be obtained from the IETF on-line IPR repository at 1033 http://www.ietf.org/ipr. 1035 The IETF invites any interested party to bring to its attention any 1036 copyrights, patents or patent applications, or other proprietary 1037 rights that may cover technology that may be required to implement 1038 this standard. Please address the information to the IETF at 1039 ietf-ipr@ietf.org.