idnits 2.17.1 draft-ietf-httpbis-p4-conditional-00.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 26. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 838. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 849. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 856. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 862. 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 : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC2616]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 127: '...rong entity tag" MAY be shared by two ...' RFC 2119 keyword, line 130: '...d by the "W/" prefix, MAY be shared by...' RFC 2119 keyword, line 135: '... An entity tag MUST be unique across...' RFC 2119 keyword, line 136: '...esource. A given entity tag value MAY...' RFC 2119 keyword, line 147: '...s not been modified, the server SHOULD...' (53 more instances...) -- The draft header indicates that this document obsoletes RFC2068, but the abstract doesn't seem to mention this, which it should. 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 (December 20, 2007) is 5972 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-00 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-00 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-00 ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 6 errors (**), 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: 2068, 2616 J. Gettys 5 (if approved) One Laptop per Child 6 Intended status: Standards Track J. Mogul 7 Expires: June 22, 2008 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 December 20, 2007 18 HTTP/1.1, part 4: Conditional Requests 19 draft-ietf-httpbis-p4-conditional-00 21 Status of this Memo 23 By submitting this Internet-Draft, each author represents that any 24 applicable patent or other IPR claims of which he or she is aware 25 have been or will be disclosed, and any of which he or she becomes 26 aware will be disclosed, in accordance with Section 6 of BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF), its areas, and its working groups. Note that 30 other groups may also distribute working documents as Internet- 31 Drafts. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 The list of current Internet-Drafts can be accessed at 39 http://www.ietf.org/ietf/1id-abstracts.txt. 41 The list of Internet-Draft Shadow Directories can be accessed at 42 http://www.ietf.org/shadow.html. 44 This Internet-Draft will expire on June 22, 2008. 46 Copyright Notice 48 Copyright (C) The IETF Trust (2007). 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 This version of the HTTP specification contains only minimal 64 editorial changes from [RFC2616] (abstract, introductory paragraph, 65 and authors' addresses). All other changes are due to partitioning 66 the original into seven mostly independent parts. The intent is for 67 readers of future drafts to able to use draft 00 as the basis for 68 comparison when the WG makes later changes to the specification text. 69 This draft will shortly be followed by draft 01 (containing the first 70 round of changes that have already been agreed to on the mailing 71 list). There is no point in reviewing this draft other than to 72 verify that the partitioning has been done correctly. Roy T. 73 Fielding, Yves Lafon, and Julian Reschke will be the editors after 74 draft 00 is submitted. 76 Discussion of this draft should take place on the HTTPBIS working 77 group mailing list (ietf-http-wg@w3.org). The current issues list is 78 at and related 79 documents (including fancy diffs) can be found at 80 . 82 Table of Contents 84 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 85 2. Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . 4 86 3. Status Code Definitions . . . . . . . . . . . . . . . . . . . 4 87 3.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 4 88 3.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 5 89 4. Weak and Strong Validators . . . . . . . . . . . . . . . . . . 5 90 5. Rules for When to Use Entity Tags and Last-Modified Dates . . 8 91 6. Header Field Definitions . . . . . . . . . . . . . . . . . . . 10 92 6.1. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 93 6.2. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 10 94 6.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 11 95 6.4. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 13 96 6.5. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 14 97 6.6. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 15 98 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 99 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 100 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 101 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 102 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 104 Intellectual Property and Copyright Statements . . . . . . . . . . 20 106 1. Introduction 108 This document will define aspects of HTTP related to conditional 109 request messages based on time stamps and entity-tags. Right now it 110 only includes the extracted relevant sections of RFC 2616 [RFC2616] 111 without edit. 113 2. Entity Tags 115 Entity tags are used for comparing two or more entities from the same 116 requested resource. HTTP/1.1 uses entity tags in the ETag 117 (Section 6.1), If-Match (Section 6.2), If-None-Match (Section 6.4), 118 and If-Range (Section 5.3 of [Part5]) header fields. The definition 119 of how they are used and compared as cache validators is in 120 Section 4. An entity tag consists of an opaque quoted string, 121 possibly prefixed by a weakness indicator. 123 entity-tag = [ weak ] opaque-tag 124 weak = "W/" 125 opaque-tag = quoted-string 127 A "strong entity tag" MAY be shared by two entities of a resource 128 only if they are equivalent by octet equality. 130 A "weak entity tag," indicated by the "W/" prefix, MAY be shared by 131 two entities of a resource only if the entities are equivalent and 132 could be substituted for each other with no significant change in 133 semantics. A weak entity tag can only be used for weak comparison. 135 An entity tag MUST be unique across all versions of all entities 136 associated with a particular resource. A given entity tag value MAY 137 be used for entities obtained by requests on different URIs. The use 138 of the same entity tag value in conjunction with entities obtained by 139 requests on different URIs does not imply the equivalence of those 140 entities. 142 3. Status Code Definitions 144 3.1. 304 Not Modified 146 If the client has performed a conditional GET request and access is 147 allowed, but the document has not been modified, the server SHOULD 148 respond with this status code. The 304 response MUST NOT contain a 149 message-body, and thus is always terminated by the first empty line 150 after the header fields. 152 The response MUST include the following header fields: 154 o Date, unless its omission is required by Section 8.3.1 of [Part1] 156 If a clockless origin server obeys these rules, and proxies and 157 clients add their own Date to any response received without one (as 158 already specified by [RFC2068], section 14.19), caches will operate 159 correctly. 161 o ETag and/or Content-Location, if the header would have been sent 162 in a 200 response to the same request 164 o Expires, Cache-Control, and/or Vary, if the field-value might 165 differ from that sent in any previous response for the same 166 variant 168 If the conditional GET used a strong cache validator (see [Part6]), 169 the response SHOULD NOT include other entity-headers. Otherwise 170 (i.e., the conditional GET used a weak validator), the response MUST 171 NOT include other entity-headers; this prevents inconsistencies 172 between cached entity-bodies and updated headers. 174 If a 304 response indicates an entity not currently cached, then the 175 cache MUST disregard the response and repeat the request without the 176 conditional. 178 If a cache uses a received 304 response to update a cache entry, the 179 cache MUST update the entry to reflect any new field values given in 180 the response. 182 3.2. 412 Precondition Failed 184 The precondition given in one or more of the request-header fields 185 evaluated to false when it was tested on the server. This response 186 code allows the client to place preconditions on the current resource 187 metainformation (header field data) and thus prevent the requested 188 method from being applied to a resource other than the one intended. 190 4. Weak and Strong Validators 192 Since both origin servers and caches will compare two validators to 193 decide if they represent the same or different entities, one normally 194 would expect that if the entity (the entity-body or any entity- 195 headers) changes in any way, then the associated validator would 196 change as well. If this is true, then we call this validator a 197 "strong validator." 198 However, there might be cases when a server prefers to change the 199 validator only on semantically significant changes, and not when 200 insignificant aspects of the entity change. A validator that does 201 not always change when the resource changes is a "weak validator." 203 Entity tags are normally "strong validators," but the protocol 204 provides a mechanism to tag an entity tag as "weak." One can think 205 of a strong validator as one that changes whenever the bits of an 206 entity changes, while a weak value changes whenever the meaning of an 207 entity changes. Alternatively, one can think of a strong validator 208 as part of an identifier for a specific entity, while a weak 209 validator is part of an identifier for a set of semantically 210 equivalent entities. 212 Note: One example of a strong validator is an integer that is 213 incremented in stable storage every time an entity is changed. 215 An entity's modification time, if represented with one-second 216 resolution, could be a weak validator, since it is possible that 217 the resource might be modified twice during a single second. 219 Support for weak validators is optional. However, weak validators 220 allow for more efficient caching of equivalent objects; for 221 example, a hit counter on a site is probably good enough if it is 222 updated every few days or weeks, and any value during that period 223 is likely "good enough" to be equivalent. 225 A "use" of a validator is either when a client generates a request 226 and includes the validator in a validating header field, or when a 227 server compares two validators. 229 Strong validators are usable in any context. Weak validators are 230 only usable in contexts that do not depend on exact equality of an 231 entity. For example, either kind is usable for a conditional GET of 232 a full entity. However, only a strong validator is usable for a sub- 233 range retrieval, since otherwise the client might end up with an 234 internally inconsistent entity. 236 Clients MAY issue simple (non-subrange) GET requests with either weak 237 validators or strong validators. Clients MUST NOT use weak 238 validators in other forms of request. 240 The only function that the HTTP/1.1 protocol defines on validators is 241 comparison. There are two validator comparison functions, depending 242 on whether the comparison context allows the use of weak validators 243 or not: 245 o The strong comparison function: in order to be considered equal, 246 both validators MUST be identical in every way, and both MUST NOT 247 be weak. 249 o The weak comparison function: in order to be considered equal, 250 both validators MUST be identical in every way, but either or both 251 of them MAY be tagged as "weak" without affecting the result. 253 An entity tag is strong unless it is explicitly tagged as weak. 254 Section 2 gives the syntax for entity tags. 256 A Last-Modified time, when used as a validator in a request, is 257 implicitly weak unless it is possible to deduce that it is strong, 258 using the following rules: 260 o The validator is being compared by an origin server to the actual 261 current validator for the entity and, 263 o That origin server reliably knows that the associated entity did 264 not change twice during the second covered by the presented 265 validator. 267 or 269 o The validator is about to be used by a client in an If-Modified- 270 Since or If-Unmodified-Since header, because the client has a 271 cache entry for the associated entity, and 273 o That cache entry includes a Date value, which gives the time when 274 the origin server sent the original response, and 276 o The presented Last-Modified time is at least 60 seconds before the 277 Date value. 279 or 281 o The validator is being compared by an intermediate cache to the 282 validator stored in its cache entry for the entity, and 284 o That cache entry includes a Date value, which gives the time when 285 the origin server sent the original response, and 287 o The presented Last-Modified time is at least 60 seconds before the 288 Date value. 290 This method relies on the fact that if two different responses were 291 sent by the origin server during the same second, but both had the 292 same Last-Modified time, then at least one of those responses would 293 have a Date value equal to its Last-Modified time. The arbitrary 60- 294 second limit guards against the possibility that the Date and Last- 295 Modified values are generated from different clocks, or at somewhat 296 different times during the preparation of the response. An 297 implementation MAY use a value larger than 60 seconds, if it is 298 believed that 60 seconds is too short. 300 If a client wishes to perform a sub-range retrieval on a value for 301 which it has only a Last-Modified time and no opaque validator, it 302 MAY do this only if the Last-Modified time is strong in the sense 303 described here. 305 A cache or origin server receiving a conditional request, other than 306 a full-body GET request, MUST use the strong comparison function to 307 evaluate the condition. 309 These rules allow HTTP/1.1 caches and clients to safely perform sub- 310 range retrievals on values that have been obtained from HTTP/1.0 311 servers. 313 5. Rules for When to Use Entity Tags and Last-Modified Dates 315 We adopt a set of rules and recommendations for origin servers, 316 clients, and caches regarding when various validator types ought to 317 be used, and for what purposes. 319 HTTP/1.1 origin servers: 321 o SHOULD send an entity tag validator unless it is not feasible to 322 generate one. 324 o MAY send a weak entity tag instead of a strong entity tag, if 325 performance considerations support the use of weak entity tags, or 326 if it is unfeasible to send a strong entity tag. 328 o SHOULD send a Last-Modified value if it is feasible to send one, 329 unless the risk of a breakdown in semantic transparency that could 330 result from using this date in an If-Modified-Since header would 331 lead to serious problems. 333 In other words, the preferred behavior for an HTTP/1.1 origin server 334 is to send both a strong entity tag and a Last-Modified value. 336 In order to be legal, a strong entity tag MUST change whenever the 337 associated entity value changes in any way. A weak entity tag SHOULD 338 change whenever the associated entity changes in a semantically 339 significant way. 341 Note: in order to provide semantically transparent caching, an 342 origin server must avoid reusing a specific strong entity tag 343 value for two different entities, or reusing a specific weak 344 entity tag value for two semantically different entities. Cache 345 entries might persist for arbitrarily long periods, regardless of 346 expiration times, so it might be inappropriate to expect that a 347 cache will never again attempt to validate an entry using a 348 validator that it obtained at some point in the past. 350 HTTP/1.1 clients: 352 o If an entity tag has been provided by the origin server, MUST use 353 that entity tag in any cache-conditional request (using If-Match 354 or If-None-Match). 356 o If only a Last-Modified value has been provided by the origin 357 server, SHOULD use that value in non-subrange cache-conditional 358 requests (using If-Modified-Since). 360 o If only a Last-Modified value has been provided by an HTTP/1.0 361 origin server, MAY use that value in subrange cache-conditional 362 requests (using If-Unmodified-Since:). The user agent SHOULD 363 provide a way to disable this, in case of difficulty. 365 o If both an entity tag and a Last-Modified value have been provided 366 by the origin server, SHOULD use both validators in cache- 367 conditional requests. This allows both HTTP/1.0 and HTTP/1.1 368 caches to respond appropriately. 370 An HTTP/1.1 origin server, upon receiving a conditional request that 371 includes both a Last-Modified date (e.g., in an If-Modified-Since or 372 If-Unmodified-Since header field) and one or more entity tags (e.g., 373 in an If-Match, If-None-Match, or If-Range header field) as cache 374 validators, MUST NOT return a response status of 304 (Not Modified) 375 unless doing so is consistent with all of the conditional header 376 fields in the request. 378 An HTTP/1.1 caching proxy, upon receiving a conditional request that 379 includes both a Last-Modified date and one or more entity tags as 380 cache validators, MUST NOT return a locally cached response to the 381 client unless that cached response is consistent with all of the 382 conditional header fields in the request. 384 Note: The general principle behind these rules is that HTTP/1.1 385 servers and clients should transmit as much non-redundant 386 information as is available in their responses and requests. 387 HTTP/1.1 systems receiving this information will make the most 388 conservative assumptions about the validators they receive. 390 HTTP/1.0 clients and caches will ignore entity tags. Generally, 391 last-modified values received or used by these systems will 392 support transparent and efficient caching, and so HTTP/1.1 origin 393 servers should provide Last-Modified values. In those rare cases 394 where the use of a Last-Modified value as a validator by an 395 HTTP/1.0 system could result in a serious problem, then HTTP/1.1 396 origin servers should not provide one. 398 6. Header Field Definitions 400 This section defines the syntax and semantics of all standard 401 HTTP/1.1 header fields. For entity-header fields, both sender and 402 recipient refer to either the client or the server, depending on who 403 sends and who receives the entity. 405 6.1. ETag 407 The ETag response-header field provides the current value of the 408 entity tag for the requested variant. The headers used with entity 409 tags are described in sections 6.2, 6.4 and Section 5.3 of [Part5]. 410 The entity tag MAY be used for comparison with other entities from 411 the same resource (see Section 4). 413 ETag = "ETag" ":" entity-tag 415 Examples: 417 ETag: "xyzzy" 418 ETag: W/"xyzzy" 419 ETag: "" 421 6.2. If-Match 423 The If-Match request-header field is used with a method to make it 424 conditional. A client that has one or more entities previously 425 obtained from the resource can verify that one of those entities is 426 current by including a list of their associated entity tags in the 427 If-Match header field. Entity tags are defined in Section 2. The 428 purpose of this feature is to allow efficient updates of cached 429 information with a minimum amount of transaction overhead. It is 430 also used, on updating requests, to prevent inadvertent modification 431 of the wrong version of a resource. As a special case, the value "*" 432 matches any current entity of the resource. 434 If-Match = "If-Match" ":" ( "*" | 1#entity-tag ) 436 If any of the entity tags match the entity tag of the entity that 437 would have been returned in the response to a similar GET request 438 (without the If-Match header) on that resource, or if "*" is given 439 and any current entity exists for that resource, then the server MAY 440 perform the requested method as if the If-Match header field did not 441 exist. 443 A server MUST use the strong comparison function (see Section 4) to 444 compare the entity tags in If-Match. 446 If none of the entity tags match, or if "*" is given and no current 447 entity exists, the server MUST NOT perform the requested method, and 448 MUST return a 412 (Precondition Failed) response. This behavior is 449 most useful when the client wants to prevent an updating method, such 450 as PUT, from modifying a resource that has changed since the client 451 last retrieved it. 453 If the request would, without the If-Match header field, result in 454 anything other than a 2xx or 412 status, then the If-Match header 455 MUST be ignored. 457 The meaning of "If-Match: *" is that the method SHOULD be performed 458 if the representation selected by the origin server (or by a cache, 459 possibly using the Vary mechanism, see Section 3.5 of [Part6]) 460 exists, and MUST NOT be performed if the representation does not 461 exist. 463 A request intended to update a resource (e.g., a PUT) MAY include an 464 If-Match header field to signal that the request method MUST NOT be 465 applied if the entity corresponding to the If-Match value (a single 466 entity tag) is no longer a representation of that resource. This 467 allows the user to indicate that they do not wish the request to be 468 successful if the resource has been changed without their knowledge. 469 Examples: 471 If-Match: "xyzzy" 472 If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 473 If-Match: * 475 The result of a request having both an If-Match header field and 476 either an If-None-Match or an If-Modified-Since header fields is 477 undefined by this specification. 479 6.3. If-Modified-Since 481 The If-Modified-Since request-header field is used with a method to 482 make it conditional: if the requested variant has not been modified 483 since the time specified in this field, an entity will not be 484 returned from the server; instead, a 304 (not modified) response will 485 be returned without any message-body. 487 If-Modified-Since = "If-Modified-Since" ":" HTTP-date 489 An example of the field is: 491 If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 493 A GET method with an If-Modified-Since header and no Range header 494 requests that the identified entity be transferred only if it has 495 been modified since the date given by the If-Modified-Since header. 496 The algorithm for determining this includes the following cases: 498 1. If the request would normally result in anything other than a 200 499 (OK) status, or if the passed If-Modified-Since date is invalid, 500 the response is exactly the same as for a normal GET. A date 501 which is later than the server's current time is invalid. 503 2. If the variant has been modified since the If-Modified-Since 504 date, the response is exactly the same as for a normal GET. 506 3. If the variant has not been modified since a valid If-Modified- 507 Since date, the server SHOULD return a 304 (Not Modified) 508 response. 510 The purpose of this feature is to allow efficient updates of cached 511 information with a minimum amount of transaction overhead. 513 Note: The Range request-header field modifies the meaning of If- 514 Modified-Since; see Section 5.4 of [Part5] for full details. 516 Note: If-Modified-Since times are interpreted by the server, whose 517 clock might not be synchronized with the client. 519 Note: When handling an If-Modified-Since header field, some 520 servers will use an exact date comparison function, rather than a 521 less-than function, for deciding whether to send a 304 (Not 522 Modified) response. To get best results when sending an If- 523 Modified-Since header field for cache validation, clients are 524 advised to use the exact date string received in a previous Last- 525 Modified header field whenever possible. 527 Note: If a client uses an arbitrary date in the If-Modified-Since 528 header instead of a date taken from the Last-Modified header for 529 the same request, the client should be aware of the fact that this 530 date is interpreted in the server's understanding of time. The 531 client should consider unsynchronized clocks and rounding problems 532 due to the different encodings of time between the client and 533 server. This includes the possibility of race conditions if the 534 document has changed between the time it was first requested and 535 the If-Modified-Since date of a subsequent request, and the 536 possibility of clock-skew-related problems if the If-Modified- 537 Since date is derived from the client's clock without correction 538 to the server's clock. Corrections for different time bases 539 between client and server are at best approximate due to network 540 latency. 542 The result of a request having both an If-Modified-Since header field 543 and either an If-Match or an If-Unmodified-Since header fields is 544 undefined by this specification. 546 6.4. If-None-Match 548 The If-None-Match request-header field is used with a method to make 549 it conditional. A client that has one or more entities previously 550 obtained from the resource can verify that none of those entities is 551 current by including a list of their associated entity tags in the 552 If-None-Match header field. The purpose of this feature is to allow 553 efficient updates of cached information with a minimum amount of 554 transaction overhead. It is also used to prevent a method (e.g. 555 PUT) from inadvertently modifying an existing resource when the 556 client believes that the resource does not exist. 558 As a special case, the value "*" matches any current entity of the 559 resource. 561 If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag ) 563 If any of the entity tags match the entity tag of the entity that 564 would have been returned in the response to a similar GET request 565 (without the If-None-Match header) on that resource, or if "*" is 566 given and any current entity exists for that resource, then the 567 server MUST NOT perform the requested method, unless required to do 568 so because the resource's modification date fails to match that 569 supplied in an If-Modified-Since header field in the request. 570 Instead, if the request method was GET or HEAD, the server SHOULD 571 respond with a 304 (Not Modified) response, including the cache- 572 related header fields (particularly ETag) of one of the entities that 573 matched. For all other request methods, the server MUST respond with 574 a status of 412 (Precondition Failed). 576 See Section 4 for rules on how to determine if two entities tags 577 match. The weak comparison function can only be used with GET or 578 HEAD requests. 580 If none of the entity tags match, then the server MAY perform the 581 requested method as if the If-None-Match header field did not exist, 582 but MUST also ignore any If-Modified-Since header field(s) in the 583 request. That is, if no entity tags match, then the server MUST NOT 584 return a 304 (Not Modified) response. 586 If the request would, without the If-None-Match header field, result 587 in anything other than a 2xx or 304 status, then the If-None-Match 588 header MUST be ignored. (See Section 5 for a discussion of server 589 behavior when both If-Modified-Since and If-None-Match appear in the 590 same request.) 592 The meaning of "If-None-Match: *" is that the method MUST NOT be 593 performed if the representation selected by the origin server (or by 594 a cache, possibly using the Vary mechanism, see Section 3.5 of 595 [Part6]) exists, and SHOULD be performed if the representation does 596 not exist. This feature is intended to be useful in preventing races 597 between PUT operations. 599 Examples: 601 If-None-Match: "xyzzy" 602 If-None-Match: W/"xyzzy" 603 If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" 604 If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" 605 If-None-Match: * 607 The result of a request having both an If-None-Match header field and 608 either an If-Match or an If-Unmodified-Since header fields is 609 undefined by this specification. 611 6.5. If-Unmodified-Since 613 The If-Unmodified-Since request-header field is used with a method to 614 make it conditional. If the requested resource has not been modified 615 since the time specified in this field, the server SHOULD perform the 616 requested operation as if the If-Unmodified-Since header were not 617 present. 619 If the requested variant has been modified since the specified time, 620 the server MUST NOT perform the requested operation, and MUST return 621 a 412 (Precondition Failed). 623 If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date 625 An example of the field is: 627 If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT 629 If the request normally (i.e., without the If-Unmodified-Since 630 header) would result in anything other than a 2xx or 412 status, the 631 If-Unmodified-Since header SHOULD be ignored. 633 If the specified date is invalid, the header is ignored. 635 The result of a request having both an If-Unmodified-Since header 636 field and either an If-None-Match or an If-Modified-Since header 637 fields is undefined by this specification. 639 6.6. Last-Modified 641 The Last-Modified entity-header field indicates the date and time at 642 which the origin server believes the variant was last modified. 644 Last-Modified = "Last-Modified" ":" HTTP-date 646 An example of its use is 648 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 650 The exact meaning of this header field depends on the implementation 651 of the origin server and the nature of the original resource. For 652 files, it may be just the file system last-modified time. For 653 entities with dynamically included parts, it may be the most recent 654 of the set of last-modify times for its component parts. For 655 database gateways, it may be the last-update time stamp of the 656 record. For virtual objects, it may be the last time the internal 657 state changed. 659 An origin server MUST NOT send a Last-Modified date which is later 660 than the server's time of message origination. In such cases, where 661 the resource's last modification would indicate some time in the 662 future, the server MUST replace that date with the message 663 origination date. 665 An origin server SHOULD obtain the Last-Modified value of the entity 666 as close as possible to the time that it generates the Date value of 667 its response. This allows a recipient to make an accurate assessment 668 of the entity's modification time, especially if the entity changes 669 near the time that the response is generated. 671 HTTP/1.1 servers SHOULD send Last-Modified whenever feasible. 673 7. IANA Considerations 675 TBD. 677 8. Security Considerations 679 No additional security considerations have been identified beyond 680 those applicable to HTTP in general [Part1]. 682 9. Acknowledgments 684 Based on an XML translation of RFC 2616 by Julian Reschke. 686 10. References 688 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 689 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 690 part 1: URIs, Connections, and Message Parsing", 691 draft-ietf-httpbis-p1-messaging-00 (work in progress), 692 December 2007. 694 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 695 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 696 part 5: Range Requests and Partial Responses", 697 draft-ietf-httpbis-p5-range-00 (work in progress), 698 December 2007. 700 [Part6] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 701 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 702 part 6: Caching", draft-ietf-httpbis-p6-cache-00 (work in 703 progress), December 2007. 705 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 706 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 707 RFC 2068, January 1997. 709 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 710 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 711 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 713 Index 715 3 716 304 Not Modified (status code) 4 718 4 719 412 Precondition Failed (status code) 5 721 E 722 ETag header 10 724 G 725 Grammar 726 entity-tag 4 727 ETag 10 728 If-Match 10 729 If-Modified-Since 12 730 If-None-Match 13 731 If-Unmodified-Since 14 732 Last-Modified 15 733 opaque-tag 4 734 weak 4 736 H 737 Headers 738 ETag 10 739 If-Match 10 740 If-Modified-Since 11 741 If-None-Match 13 742 If-Unmodified-Since 14 743 Last-Modified 15 745 I 746 If-Match header 10 747 If-Modified-Since header 11 748 If-None-Match header 13 749 If-Unmodified-Since header 14 751 L 752 Last-Modified header 15 754 S 755 Status Codes 756 304 Not Modified 4 757 412 Precondition Failed 5 759 Authors' Addresses 761 Roy T. Fielding (editor) 762 Day Software 763 23 Corporate Plaza DR, Suite 280 764 Newport Beach, CA 92660 765 USA 767 Phone: +1-949-706-5300 768 Fax: +1-949-706-5305 769 Email: fielding@gbiv.com 770 URI: http://roy.gbiv.com/ 772 Jim Gettys 773 One Laptop per Child 774 21 Oak Knoll Road 775 Carlisle, MA 01741 776 USA 778 Email: jg@laptop.org 779 URI: http://www.laptop.org/ 781 Jeffrey C. Mogul 782 Hewlett-Packard Company 783 HP Labs, Large Scale Systems Group 784 1501 Page Mill Road, MS 1177 785 Palo Alto, CA 94304 786 USA 788 Email: JeffMogul@acm.org 790 Henrik Frystyk Nielsen 791 Microsoft Corporation 792 1 Microsoft Way 793 Redmond, WA 98052 794 USA 796 Email: henrikn@microsoft.com 797 Larry Masinter 798 Adobe Systems, Incorporated 799 345 Park Ave 800 San Jose, CA 95110 801 USA 803 Email: LMM@acm.org 804 URI: http://larry.masinter.net/ 806 Paul J. Leach 807 Microsoft Corporation 808 1 Microsoft Way 809 Redmond, WA 98052 811 Email: paulle@microsoft.com 813 Tim Berners-Lee 814 World Wide Web Consortium 815 MIT Computer Science and Artificial Intelligence Laboratory 816 The Stata Center, Building 32 817 32 Vassar Street 818 Cambridge, MA 02139 819 USA 821 Email: timbl@w3.org 822 URI: http://www.w3.org/People/Berners-Lee/ 824 Full Copyright Statement 826 Copyright (C) The IETF Trust (2007). 828 This document is subject to the rights, licenses and restrictions 829 contained in BCP 78, and except as set forth therein, the authors 830 retain all their rights. 832 This document and the information contained herein are provided on an 833 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 834 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 835 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 836 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 837 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 838 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 840 Intellectual Property 842 The IETF takes no position regarding the validity or scope of any 843 Intellectual Property Rights or other rights that might be claimed to 844 pertain to the implementation or use of the technology described in 845 this document or the extent to which any license under such rights 846 might or might not be available; nor does it represent that it has 847 made any independent effort to identify any such rights. Information 848 on the procedures with respect to rights in RFC documents can be 849 found in BCP 78 and BCP 79. 851 Copies of IPR disclosures made to the IETF Secretariat and any 852 assurances of licenses to be made available, or the result of an 853 attempt made to obtain a general license or permission for the use of 854 such proprietary rights by implementers or users of this 855 specification can be obtained from the IETF on-line IPR repository at 856 http://www.ietf.org/ipr. 858 The IETF invites any interested party to bring to its attention any 859 copyrights, patents or patent applications, or other proprietary 860 rights that may cover technology that may be required to implement 861 this standard. Please address the information to the IETF at 862 ietf-ipr@ietf.org. 864 Acknowledgment 866 Funding for the RFC Editor function is provided by the IETF 867 Administrative Support Activity (IASA).