source: draft-ietf-httpbis/01/draft-ietf-httpbis-p4-conditional-01.txt @ 166

Last change on this file since 166 was 166, checked in by fielding@…, 12 years ago

generated draft 01

  • Property svn:eol-style set to native
File size: 43.0 KB
Line 
1
2
3
4Network Working Group                                   R. Fielding, Ed.
5Internet-Draft                                              Day Software
6Obsoletes: 2616 (if approved)                                  J. Gettys
7Intended status: Standards Track                    One Laptop per Child
8Expires: July 15, 2008                                          J. Mogul
9                                                                      HP
10                                                              H. Frystyk
11                                                               Microsoft
12                                                             L. Masinter
13                                                           Adobe Systems
14                                                                P. Leach
15                                                               Microsoft
16                                                          T. Berners-Lee
17                                                                 W3C/MIT
18                                                           Y. Lafon, Ed.
19                                                                     W3C
20                                                         J. Reschke, Ed.
21                                                              greenbytes
22                                                        January 12, 2008
23
24
25                 HTTP/1.1, part 4: Conditional Requests
26                  draft-ietf-httpbis-p4-conditional-01
27
28Status of this Memo
29
30   By submitting this Internet-Draft, each author represents that any
31   applicable patent or other IPR claims of which he or she is aware
32   have been or will be disclosed, and any of which he or she becomes
33   aware will be disclosed, in accordance with Section 6 of BCP 79.
34
35   Internet-Drafts are working documents of the Internet Engineering
36   Task Force (IETF), its areas, and its working groups.  Note that
37   other groups may also distribute working documents as Internet-
38   Drafts.
39
40   Internet-Drafts are draft documents valid for a maximum of six months
41   and may be updated, replaced, or obsoleted by other documents at any
42   time.  It is inappropriate to use Internet-Drafts as reference
43   material or to cite them other than as "work in progress."
44
45   The list of current Internet-Drafts can be accessed at
46   http://www.ietf.org/ietf/1id-abstracts.txt.
47
48   The list of Internet-Draft Shadow Directories can be accessed at
49   http://www.ietf.org/shadow.html.
50
51   This Internet-Draft will expire on July 15, 2008.
52
53
54
55Fielding, et al.          Expires July 15, 2008                 [Page 1]
56
57Internet-Draft              HTTP/1.1, Part 4                January 2008
58
59
60Copyright Notice
61
62   Copyright (C) The IETF Trust (2008).
63
64Abstract
65
66   The Hypertext Transfer Protocol (HTTP) is an application-level
67   protocol for distributed, collaborative, hypermedia information
68   systems.  HTTP has been in use by the World Wide Web global
69   information initiative since 1990.  This document is Part 4 of the
70   seven-part specification that defines the protocol referred to as
71   "HTTP/1.1" and, taken together, obsoletes RFC 2616.  Part 4 defines
72   request header fields for indicating conditional requests and the
73   rules for constructing responses to those requests.
74
75Editorial Note (To be removed by RFC Editor)
76
77   Discussion of this draft should take place on the HTTPBIS working
78   group mailing list (ietf-http-wg@w3.org).  The current issues list is
79   at <http://www.tools.ietf.org/wg/httpbis/trac/report/11> and related
80   documents (including fancy diffs) can be found at
81   <http://www.tools.ietf.org/wg/httpbis/>.
82
83   This draft incorporates those issue resolutions that were either
84   collected in the original RFC2616 errata list
85   (<http://purl.org/NET/http-errata>), or which were agreed upon on the
86   mailing list between October 2006 and November 2007 (as published in
87   "draft-lafon-rfc2616bis-03").
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111Fielding, et al.          Expires July 15, 2008                 [Page 2]
112
113Internet-Draft              HTTP/1.1, Part 4                January 2008
114
115
116Table of Contents
117
118   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
119     1.1.  Requirements . . . . . . . . . . . . . . . . . . . . . . .  4
120   2.  Entity Tags  . . . . . . . . . . . . . . . . . . . . . . . . .  4
121   3.  Status Code Definitions  . . . . . . . . . . . . . . . . . . .  5
122     3.1.  304 Not Modified . . . . . . . . . . . . . . . . . . . . .  5
123     3.2.  412 Precondition Failed  . . . . . . . . . . . . . . . . .  6
124   4.  Weak and Strong Validators . . . . . . . . . . . . . . . . . .  6
125   5.  Rules for When to Use Entity Tags and Last-Modified Dates  . .  9
126   6.  Header Field Definitions . . . . . . . . . . . . . . . . . . . 10
127     6.1.  ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
128     6.2.  If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 11
129     6.3.  If-Modified-Since  . . . . . . . . . . . . . . . . . . . . 12
130     6.4.  If-None-Match  . . . . . . . . . . . . . . . . . . . . . . 14
131     6.5.  If-Unmodified-Since  . . . . . . . . . . . . . . . . . . . 15
132     6.6.  Last-Modified  . . . . . . . . . . . . . . . . . . . . . . 16
133   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
134   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 16
135   9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 16
136   10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
137     10.1. Normative References . . . . . . . . . . . . . . . . . . . 17
138     10.2. Informative References . . . . . . . . . . . . . . . . . . 17
139   Appendix A.  Compatibility with Previous Versions  . . . . . . . . 17
140     A.1.  Changes from RFC 2616  . . . . . . . . . . . . . . . . . . 17
141   Appendix B.  Change Log (to be removed by RFC Editor before
142                publication)  . . . . . . . . . . . . . . . . . . . . 17
143     B.1.  Since RFC2616  . . . . . . . . . . . . . . . . . . . . . . 17
144     B.2.  Since draft-ietf-httpbis-p4-conditional-00 . . . . . . . . 18
145   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
146   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19
147   Intellectual Property and Copyright Statements . . . . . . . . . . 22
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167Fielding, et al.          Expires July 15, 2008                 [Page 3]
168
169Internet-Draft              HTTP/1.1, Part 4                January 2008
170
171
1721.  Introduction
173
174   This document defines HTTP/1.1 response metadata for indicating
175   potential changes to payload content, including modification time
176   stamps and opaque entity-tags, and the HTTP conditional request
177   mechanisms that allow preconditions to be placed on a request method.
178   Conditional GET requests allow for efficient cache updates.  Other
179   conditional request methods are used to protect against overwriting
180   or misunderstanding the state of a resource that has been changed
181   unbeknownst to the requesting client.
182
183   This document is currently disorganized in order to minimize the
184   changes between drafts and enable reviewers to see the smaller errata
185   changes.  The next draft will reorganize the sections to better
186   reflect the content.  In particular, the sections on resource
187   metadata will be discussed first and then followed by each
188   conditional request-header, concluding with a definition of
189   precedence and the expectation of ordering strong validator checks
190   before weak validator checks.  It is likely that more content from
191   [Part6] will migrate to this part, where appropriate.  The current
192   mess reflects how widely dispersed these topics and associated
193   requirements had become in [RFC2616].
194
1951.1.  Requirements
196
197   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
198   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
199   document are to be interpreted as described in [RFC2119].
200
201   An implementation is not compliant if it fails to satisfy one or more
202   of the MUST or REQUIRED level requirements for the protocols it
203   implements.  An implementation that satisfies all the MUST or
204   REQUIRED level and all the SHOULD level requirements for its
205   protocols is said to be "unconditionally compliant"; one that
206   satisfies all the MUST level requirements but not all the SHOULD
207   level requirements for its protocols is said to be "conditionally
208   compliant."
209
210
2112.  Entity Tags
212
213   Entity tags are used for comparing two or more entities from the same
214   requested resource.  HTTP/1.1 uses entity tags in the ETag
215   (Section 6.1), If-Match (Section 6.2), If-None-Match (Section 6.4),
216   and If-Range (Section 5.3 of [Part5]) header fields.  The definition
217   of how they are used and compared as cache validators is in
218   Section 4.  An entity tag consists of an opaque quoted string,
219   possibly prefixed by a weakness indicator.
220
221
222
223Fielding, et al.          Expires July 15, 2008                 [Page 4]
224
225Internet-Draft              HTTP/1.1, Part 4                January 2008
226
227
228     entity-tag = [ weak ] opaque-tag
229     weak       = "W/"
230     opaque-tag = quoted-string
231
232   A "strong entity tag" MAY be shared by two entities of a resource
233   only if they are equivalent by octet equality.
234
235   A "weak entity tag," indicated by the "W/" prefix, MAY be shared by
236   two entities of a resource only if the entities are equivalent and
237   could be substituted for each other with no significant change in
238   semantics.  A weak entity tag can only be used for weak comparison.
239
240   An entity tag MUST be unique across all versions of all entities
241   associated with a particular resource.  A given entity tag value MAY
242   be used for entities obtained by requests on different URIs.  The use
243   of the same entity tag value in conjunction with entities obtained by
244   requests on different URIs does not imply the equivalence of those
245   entities.
246
247
2483.  Status Code Definitions
249
2503.1.  304 Not Modified
251
252   If the client has performed a conditional GET request and access is
253   allowed, but the document has not been modified, the server SHOULD
254   respond with this status code.  The 304 response MUST NOT contain a
255   message-body, and thus is always terminated by the first empty line
256   after the header fields.
257
258   The response MUST include the following header fields:
259
260   o  Date, unless its omission is required by Section 8.3.1 of [Part1]
261
262   If a clockless origin server obeys these rules, and proxies and
263   clients add their own Date to any response received without one (as
264   already specified by [RFC2068], Section 14.19), caches will operate
265   correctly.
266
267   o  ETag and/or Content-Location, if the header would have been sent
268      in a 200 response to the same request
269
270   o  Expires, Cache-Control, and/or Vary, if the field-value might
271      differ from that sent in any previous response for the same
272      variant
273
274   If the conditional GET used a strong cache validator (see Section 4),
275   the response SHOULD NOT include other entity-headers.  Otherwise
276
277
278
279Fielding, et al.          Expires July 15, 2008                 [Page 5]
280
281Internet-Draft              HTTP/1.1, Part 4                January 2008
282
283
284   (i.e., the conditional GET used a weak validator), the response MUST
285   NOT include other entity-headers; this prevents inconsistencies
286   between cached entity-bodies and updated headers.
287
288   If a 304 response indicates an entity not currently cached, then the
289   cache MUST disregard the response and repeat the request without the
290   conditional.
291
292   If a cache uses a received 304 response to update a cache entry, the
293   cache MUST update the entry to reflect any new field values given in
294   the response.
295
2963.2.  412 Precondition Failed
297
298   The precondition given in one or more of the request-header fields
299   evaluated to false when it was tested on the server.  This response
300   code allows the client to place preconditions on the current resource
301   metainformation (header field data) and thus prevent the requested
302   method from being applied to a resource other than the one intended.
303
304
3054.  Weak and Strong Validators
306
307   Since both origin servers and caches will compare two validators to
308   decide if they represent the same or different entities, one normally
309   would expect that if the entity (the entity-body or any entity-
310   headers) changes in any way, then the associated validator would
311   change as well.  If this is true, then we call this validator a
312   "strong validator."
313
314   However, there might be cases when a server prefers to change the
315   validator only on semantically significant changes, and not when
316   insignificant aspects of the entity change.  A validator that does
317   not always change when the resource changes is a "weak validator."
318
319   Entity tags are normally "strong validators," but the protocol
320   provides a mechanism to tag an entity tag as "weak."  One can think
321   of a strong validator as one that changes whenever the bits of an
322   entity changes, while a weak value changes whenever the meaning of an
323   entity changes.  Alternatively, one can think of a strong validator
324   as part of an identifier for a specific entity, while a weak
325   validator is part of an identifier for a set of semantically
326   equivalent entities.
327
328      Note: One example of a strong validator is an integer that is
329      incremented in stable storage every time an entity is changed.
330
331
332
333
334
335Fielding, et al.          Expires July 15, 2008                 [Page 6]
336
337Internet-Draft              HTTP/1.1, Part 4                January 2008
338
339
340      An entity's modification time, if represented with one-second
341      resolution, could be a weak validator, since it is possible that
342      the resource might be modified twice during a single second.
343
344      Support for weak validators is optional.  However, weak validators
345      allow for more efficient caching of equivalent objects; for
346      example, a hit counter on a site is probably good enough if it is
347      updated every few days or weeks, and any value during that period
348      is likely "good enough" to be equivalent.
349
350   A "use" of a validator is either when a client generates a request
351   and includes the validator in a validating header field, or when a
352   server compares two validators.
353
354   Strong validators are usable in any context.  Weak validators are
355   only usable in contexts that do not depend on exact equality of an
356   entity.  For example, either kind is usable for a conditional GET of
357   a full entity.  However, only a strong validator is usable for a sub-
358   range retrieval, since otherwise the client might end up with an
359   internally inconsistent entity.
360
361   Clients MAY issue simple (non-subrange) GET requests with either weak
362   validators or strong validators.  Clients MUST NOT use weak
363   validators in other forms of request.
364
365   The only function that the HTTP/1.1 protocol defines on validators is
366   comparison.  There are two validator comparison functions, depending
367   on whether the comparison context allows the use of weak validators
368   or not:
369
370   o  The strong comparison function: in order to be considered equal,
371      both validators MUST be identical in every way, and both MUST NOT
372      be weak.
373
374   o  The weak comparison function: in order to be considered equal,
375      both validators MUST be identical in every way, but either or both
376      of them MAY be tagged as "weak" without affecting the result.
377
378   An entity tag is strong unless it is explicitly tagged as weak.
379   Section 2 gives the syntax for entity tags.
380
381   A Last-Modified time, when used as a validator in a request, is
382   implicitly weak unless it is possible to deduce that it is strong,
383   using the following rules:
384
385   o  The validator is being compared by an origin server to the actual
386      current validator for the entity and,
387
388
389
390
391Fielding, et al.          Expires July 15, 2008                 [Page 7]
392
393Internet-Draft              HTTP/1.1, Part 4                January 2008
394
395
396   o  That origin server reliably knows that the associated entity did
397      not change twice during the second covered by the presented
398      validator.
399
400   or
401
402   o  The validator is about to be used by a client in an If-Modified-
403      Since or If-Unmodified-Since header, because the client has a
404      cache entry for the associated entity, and
405
406   o  That cache entry includes a Date value, which gives the time when
407      the origin server sent the original response, and
408
409   o  The presented Last-Modified time is at least 60 seconds before the
410      Date value.
411
412   or
413
414   o  The validator is being compared by an intermediate cache to the
415      validator stored in its cache entry for the entity, and
416
417   o  That cache entry includes a Date value, which gives the time when
418      the origin server sent the original response, and
419
420   o  The presented Last-Modified time is at least 60 seconds before the
421      Date value.
422
423   This method relies on the fact that if two different responses were
424   sent by the origin server during the same second, but both had the
425   same Last-Modified time, then at least one of those responses would
426   have a Date value equal to its Last-Modified time.  The arbitrary 60-
427   second limit guards against the possibility that the Date and Last-
428   Modified values are generated from different clocks, or at somewhat
429   different times during the preparation of the response.  An
430   implementation MAY use a value larger than 60 seconds, if it is
431   believed that 60 seconds is too short.
432
433   If a client wishes to perform a sub-range retrieval on a value for
434   which it has only a Last-Modified time and no opaque validator, it
435   MAY do this only if the Last-Modified time is strong in the sense
436   described here.
437
438   A cache or origin server receiving a conditional request, other than
439   a full-body GET request, MUST use the strong comparison function to
440   evaluate the condition.
441
442   These rules allow HTTP/1.1 caches and clients to safely perform sub-
443   range retrievals on values that have been obtained from HTTP/1.0
444
445
446
447Fielding, et al.          Expires July 15, 2008                 [Page 8]
448
449Internet-Draft              HTTP/1.1, Part 4                January 2008
450
451
452   servers.
453
454
4555.  Rules for When to Use Entity Tags and Last-Modified Dates
456
457   We adopt a set of rules and recommendations for origin servers,
458   clients, and caches regarding when various validator types ought to
459   be used, and for what purposes.
460
461   HTTP/1.1 origin servers:
462
463   o  SHOULD send an entity tag validator unless it is not feasible to
464      generate one.
465
466   o  MAY send a weak entity tag instead of a strong entity tag, if
467      performance considerations support the use of weak entity tags, or
468      if it is unfeasible to send a strong entity tag.
469
470   o  SHOULD send a Last-Modified value if it is feasible to send one,
471      unless the risk of a breakdown in semantic transparency that could
472      result from using this date in an If-Modified-Since header would
473      lead to serious problems.
474
475   In other words, the preferred behavior for an HTTP/1.1 origin server
476   is to send both a strong entity tag and a Last-Modified value.
477
478   In order to be legal, a strong entity tag MUST change whenever the
479   associated entity value changes in any way.  A weak entity tag SHOULD
480   change whenever the associated entity changes in a semantically
481   significant way.
482
483      Note: in order to provide semantically transparent caching, an
484      origin server must avoid reusing a specific strong entity tag
485      value for two different entities, or reusing a specific weak
486      entity tag value for two semantically different entities.  Cache
487      entries might persist for arbitrarily long periods, regardless of
488      expiration times, so it might be inappropriate to expect that a
489      cache will never again attempt to validate an entry using a
490      validator that it obtained at some point in the past.
491
492   HTTP/1.1 clients:
493
494   o  If an entity tag has been provided by the origin server, MUST use
495      that entity tag in any cache-conditional request (using If-Match
496      or If-None-Match).
497
498   o  If only a Last-Modified value has been provided by the origin
499      server, SHOULD use that value in non-subrange cache-conditional
500
501
502
503Fielding, et al.          Expires July 15, 2008                 [Page 9]
504
505Internet-Draft              HTTP/1.1, Part 4                January 2008
506
507
508      requests (using If-Modified-Since).
509
510   o  If only a Last-Modified value has been provided by an HTTP/1.0
511      origin server, MAY use that value in subrange cache-conditional
512      requests (using If-Unmodified-Since:).  The user agent SHOULD
513      provide a way to disable this, in case of difficulty.
514
515   o  If both an entity tag and a Last-Modified value have been provided
516      by the origin server, SHOULD use both validators in cache-
517      conditional requests.  This allows both HTTP/1.0 and HTTP/1.1
518      caches to respond appropriately.
519
520   An HTTP/1.1 origin server, upon receiving a conditional request that
521   includes both a Last-Modified date (e.g., in an If-Modified-Since or
522   If-Unmodified-Since header field) and one or more entity tags (e.g.,
523   in an If-Match, If-None-Match, or If-Range header field) as cache
524   validators, MUST NOT return a response status of 304 (Not Modified)
525   unless doing so is consistent with all of the conditional header
526   fields in the request.
527
528   An HTTP/1.1 caching proxy, upon receiving a conditional request that
529   includes both a Last-Modified date and one or more entity tags as
530   cache validators, MUST NOT return a locally cached response to the
531   client unless that cached response is consistent with all of the
532   conditional header fields in the request.
533
534      Note: The general principle behind these rules is that HTTP/1.1
535      servers and clients should transmit as much non-redundant
536      information as is available in their responses and requests.
537      HTTP/1.1 systems receiving this information will make the most
538      conservative assumptions about the validators they receive.
539
540      HTTP/1.0 clients and caches will ignore entity tags.  Generally,
541      last-modified values received or used by these systems will
542      support transparent and efficient caching, and so HTTP/1.1 origin
543      servers should provide Last-Modified values.  In those rare cases
544      where the use of a Last-Modified value as a validator by an
545      HTTP/1.0 system could result in a serious problem, then HTTP/1.1
546      origin servers should not provide one.
547
548
5496.  Header Field Definitions
550
551   This section defines the syntax and semantics of HTTP/1.1 header
552   fields related to conditional requests.
553
554   For entity-header fields, both sender and recipient refer to either
555   the client or the server, depending on who sends and who receives the
556
557
558
559Fielding, et al.          Expires July 15, 2008                [Page 10]
560
561Internet-Draft              HTTP/1.1, Part 4                January 2008
562
563
564   entity.
565
5666.1.  ETag
567
568   The ETag response-header field provides the current value of the
569   entity tag for the requested variant.  The headers used with entity
570   tags are described in Sections 6.2 and 6.4 of this document, and in
571   Section 5.3 of [Part5].  The entity tag MAY be used for comparison
572   with other entities from the same resource (see Section 4).
573
574     ETag = "ETag" ":" entity-tag
575
576   Examples:
577
578      ETag: "xyzzy"
579      ETag: W/"xyzzy"
580      ETag: ""
581
5826.2.  If-Match
583
584   The If-Match request-header field is used with a method to make it
585   conditional.  A client that has one or more entities previously
586   obtained from the resource can verify that one of those entities is
587   current by including a list of their associated entity tags in the
588   If-Match header field.  Entity tags are defined in Section 2.  The
589   purpose of this feature is to allow efficient updates of cached
590   information with a minimum amount of transaction overhead.  It is
591   also used, on updating requests, to prevent inadvertent modification
592   of the wrong version of a resource.  As a special case, the value "*"
593   matches any current entity of the resource.
594
595     If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
596
597   If any of the entity tags match the entity tag of the entity that
598   would have been returned in the response to a similar GET request
599   (without the If-Match header) on that resource, or if "*" is given
600   and any current entity exists for that resource, then the server MAY
601   perform the requested method as if the If-Match header field did not
602   exist.
603
604   A server MUST use the strong comparison function (see Section 4) to
605   compare the entity tags in If-Match.
606
607   If none of the entity tags match, or if "*" is given and no current
608   entity exists, the server MUST NOT perform the requested method, and
609   MUST return a 412 (Precondition Failed) response.  This behavior is
610   most useful when the client wants to prevent an updating method, such
611   as PUT, from modifying a resource that has changed since the client
612
613
614
615Fielding, et al.          Expires July 15, 2008                [Page 11]
616
617Internet-Draft              HTTP/1.1, Part 4                January 2008
618
619
620   last retrieved it.
621
622   If the request would, without the If-Match header field, result in
623   anything other than a 2xx or 412 status, then the If-Match header
624   MUST be ignored.
625
626   The meaning of "If-Match: *" is that the method SHOULD be performed
627   if the representation selected by the origin server (or by a cache,
628   possibly using the Vary mechanism, see Section 15.5 of [Part6])
629   exists, and MUST NOT be performed if the representation does not
630   exist.
631
632   A request intended to update a resource (e.g., a PUT) MAY include an
633   If-Match header field to signal that the request method MUST NOT be
634   applied if the entity corresponding to the If-Match value (a single
635   entity tag) is no longer a representation of that resource.  This
636   allows the user to indicate that they do not wish the request to be
637   successful if the resource has been changed without their knowledge.
638   Examples:
639
640       If-Match: "xyzzy"
641       If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
642       If-Match: *
643
644   The result of a request having both an If-Match header field and
645   either an If-None-Match or an If-Modified-Since header fields is
646   undefined by this specification.
647
6486.3.  If-Modified-Since
649
650   The If-Modified-Since request-header field is used with a method to
651   make it conditional: if the requested variant has not been modified
652   since the time specified in this field, an entity will not be
653   returned from the server; instead, a 304 (Not Modified) response will
654   be returned without any message-body.
655
656     If-Modified-Since = "If-Modified-Since" ":" HTTP-date
657
658   An example of the field is:
659
660       If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
661
662   A GET method with an If-Modified-Since header and no Range header
663   requests that the identified entity be transferred only if it has
664   been modified since the date given by the If-Modified-Since header.
665   The algorithm for determining this includes the following cases:
666
667
668
669
670
671Fielding, et al.          Expires July 15, 2008                [Page 12]
672
673Internet-Draft              HTTP/1.1, Part 4                January 2008
674
675
676   1.  If the request would normally result in anything other than a 200
677       (OK) status, or if the passed If-Modified-Since date is invalid,
678       the response is exactly the same as for a normal GET.  A date
679       which is later than the server's current time is invalid.
680
681   2.  If the variant has been modified since the If-Modified-Since
682       date, the response is exactly the same as for a normal GET.
683
684   3.  If the variant has not been modified since a valid If-Modified-
685       Since date, the server SHOULD return a 304 (Not Modified)
686       response.
687
688   The purpose of this feature is to allow efficient updates of cached
689   information with a minimum amount of transaction overhead.
690
691      Note: The Range request-header field modifies the meaning of If-
692      Modified-Since; see Section 5.4 of [Part5] for full details.
693
694      Note: If-Modified-Since times are interpreted by the server, whose
695      clock might not be synchronized with the client.
696
697      Note: When handling an If-Modified-Since header field, some
698      servers will use an exact date comparison function, rather than a
699      less-than function, for deciding whether to send a 304 (Not
700      Modified) response.  To get best results when sending an If-
701      Modified-Since header field for cache validation, clients are
702      advised to use the exact date string received in a previous Last-
703      Modified header field whenever possible.
704
705      Note: If a client uses an arbitrary date in the If-Modified-Since
706      header instead of a date taken from the Last-Modified header for
707      the same request, the client should be aware of the fact that this
708      date is interpreted in the server's understanding of time.  The
709      client should consider unsynchronized clocks and rounding problems
710      due to the different encodings of time between the client and
711      server.  This includes the possibility of race conditions if the
712      document has changed between the time it was first requested and
713      the If-Modified-Since date of a subsequent request, and the
714      possibility of clock-skew-related problems if the If-Modified-
715      Since date is derived from the client's clock without correction
716      to the server's clock.  Corrections for different time bases
717      between client and server are at best approximate due to network
718      latency.
719
720   The result of a request having both an If-Modified-Since header field
721   and either an If-Match or an If-Unmodified-Since header fields is
722   undefined by this specification.
723
724
725
726
727Fielding, et al.          Expires July 15, 2008                [Page 13]
728
729Internet-Draft              HTTP/1.1, Part 4                January 2008
730
731
7326.4.  If-None-Match
733
734   The If-None-Match request-header field is used with a method to make
735   it conditional.  A client that has one or more entities previously
736   obtained from the resource can verify that none of those entities is
737   current by including a list of their associated entity tags in the
738   If-None-Match header field.  The purpose of this feature is to allow
739   efficient updates of cached information with a minimum amount of
740   transaction overhead.  It is also used to prevent a method (e.g.
741   PUT) from inadvertently modifying an existing resource when the
742   client believes that the resource does not exist.
743
744   As a special case, the value "*" matches any current entity of the
745   resource.
746
747     If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
748
749   If any of the entity tags match the entity tag of the entity that
750   would have been returned in the response to a similar GET request
751   (without the If-None-Match header) on that resource, or if "*" is
752   given and any current entity exists for that resource, then the
753   server MUST NOT perform the requested method, unless required to do
754   so because the resource's modification date fails to match that
755   supplied in an If-Modified-Since header field in the request.
756   Instead, if the request method was GET or HEAD, the server SHOULD
757   respond with a 304 (Not Modified) response, including the cache-
758   related header fields (particularly ETag) of one of the entities that
759   matched.  For all other request methods, the server MUST respond with
760   a status of 412 (Precondition Failed).
761
762   See Section 4 for rules on how to determine if two entities tags
763   match.  The weak comparison function can only be used with GET or
764   HEAD requests.
765
766   If none of the entity tags match, then the server MAY perform the
767   requested method as if the If-None-Match header field did not exist,
768   but MUST also ignore any If-Modified-Since header field(s) in the
769   request.  That is, if no entity tags match, then the server MUST NOT
770   return a 304 (Not Modified) response.
771
772   If the request would, without the If-None-Match header field, result
773   in anything other than a 2xx or 304 status, then the If-None-Match
774   header MUST be ignored.  (See Section 5 for a discussion of server
775   behavior when both If-Modified-Since and If-None-Match appear in the
776   same request.)
777
778   The meaning of "If-None-Match: *" is that the method MUST NOT be
779   performed if the representation selected by the origin server (or by
780
781
782
783Fielding, et al.          Expires July 15, 2008                [Page 14]
784
785Internet-Draft              HTTP/1.1, Part 4                January 2008
786
787
788   a cache, possibly using the Vary mechanism, see Section 15.5 of
789   [Part6]) exists, and SHOULD be performed if the representation does
790   not exist.  This feature is intended to be useful in preventing races
791   between PUT operations.
792
793   Examples:
794
795       If-None-Match: "xyzzy"
796       If-None-Match: W/"xyzzy"
797       If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
798       If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
799       If-None-Match: *
800
801   The result of a request having both an If-None-Match header field and
802   either an If-Match or an If-Unmodified-Since header fields is
803   undefined by this specification.
804
8056.5.  If-Unmodified-Since
806
807   The If-Unmodified-Since request-header field is used with a method to
808   make it conditional.  If the requested resource has not been modified
809   since the time specified in this field, the server SHOULD perform the
810   requested operation as if the If-Unmodified-Since header were not
811   present.
812
813   If the requested variant has been modified since the specified time,
814   the server MUST NOT perform the requested operation, and MUST return
815   a 412 (Precondition Failed).
816
817     If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date
818
819   An example of the field is:
820
821       If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
822
823   If the request normally (i.e., without the If-Unmodified-Since
824   header) would result in anything other than a 2xx or 412 status, the
825   If-Unmodified-Since header SHOULD be ignored.
826
827   If the specified date is invalid, the header is ignored.
828
829   The result of a request having both an If-Unmodified-Since header
830   field and either an If-None-Match or an If-Modified-Since header
831   fields is undefined by this specification.
832
833
834
835
836
837
838
839Fielding, et al.          Expires July 15, 2008                [Page 15]
840
841Internet-Draft              HTTP/1.1, Part 4                January 2008
842
843
8446.6.  Last-Modified
845
846   The Last-Modified entity-header field indicates the date and time at
847   which the origin server believes the variant was last modified.
848
849     Last-Modified  = "Last-Modified" ":" HTTP-date
850
851   An example of its use is
852
853       Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
854
855   The exact meaning of this header field depends on the implementation
856   of the origin server and the nature of the original resource.  For
857   files, it may be just the file system last-modified time.  For
858   entities with dynamically included parts, it may be the most recent
859   of the set of last-modify times for its component parts.  For
860   database gateways, it may be the last-update time stamp of the
861   record.  For virtual objects, it may be the last time the internal
862   state changed.
863
864   An origin server MUST NOT send a Last-Modified date which is later
865   than the server's time of message origination.  In such cases, where
866   the resource's last modification would indicate some time in the
867   future, the server MUST replace that date with the message
868   origination date.
869
870   An origin server SHOULD obtain the Last-Modified value of the entity
871   as close as possible to the time that it generates the Date value of
872   its response.  This allows a recipient to make an accurate assessment
873   of the entity's modification time, especially if the entity changes
874   near the time that the response is generated.
875
876   HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
877
878
8797.  IANA Considerations
880
881   TBD.
882
883
8848.  Security Considerations
885
886   No additional security considerations have been identified beyond
887   those applicable to HTTP in general [Part1].
888
889
8909.  Acknowledgments
891
892
893
894
895Fielding, et al.          Expires July 15, 2008                [Page 16]
896
897Internet-Draft              HTTP/1.1, Part 4                January 2008
898
899
90010.  References
901
90210.1.  Normative References
903
904   [Part1]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
905              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
906              and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections,
907              and Message Parsing", draft-ietf-httpbis-p1-messaging-01
908              (work in progress), January 2008.
909
910   [Part5]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
911              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
912              and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and
913              Partial Responses", draft-ietf-httpbis-p5-range-01 (work
914              in progress), January 2008.
915
916   [Part6]    Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
917              Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
918              and J. Reschke, Ed., "HTTP/1.1, part 6: Caching",
919              draft-ietf-httpbis-p6-cache-01 (work in progress),
920              January 2008.
921
922   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
923              Requirement Levels", BCP 14, RFC 2119, March 1997.
924
92510.2.  Informative References
926
927   [RFC2068]  Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T.
928              Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1",
929              RFC 2068, January 1997.
930
931   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
932              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
933              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
934
935
936Appendix A.  Compatibility with Previous Versions
937
938A.1.  Changes from RFC 2616
939
940
941Appendix B.  Change Log (to be removed by RFC Editor before publication)
942
943B.1.  Since RFC2616
944
945   Extracted relevant partitions from [RFC2616].
946
947
948
949
950
951Fielding, et al.          Expires July 15, 2008                [Page 17]
952
953Internet-Draft              HTTP/1.1, Part 4                January 2008
954
955
956B.2.  Since draft-ietf-httpbis-p4-conditional-00
957
958   Closed issues:
959
960   o  <http://www3.tools.ietf.org/wg/httpbis/trac/ticket/35>: "Normative
961      and Informative references"
962
963   Other changes:
964
965   o  Move definitions of 304 and 412 condition codes from Part2.
966
967
968Index
969
970   3
971      304 Not Modified (status code)  5
972
973   4
974      412 Precondition Failed (status code)  6
975
976   E
977      ETag header  11
978
979   G
980      Grammar
981         entity-tag  5
982         ETag  11
983         If-Match  11
984         If-Modified-Since  12
985         If-None-Match  14
986         If-Unmodified-Since  15
987         Last-Modified  16
988         opaque-tag  5
989         weak  5
990
991   H
992      Headers
993         ETag  11
994         If-Match  11
995         If-Modified-Since  12
996         If-None-Match  14
997         If-Unmodified-Since  15
998         Last-Modified  16
999
1000   I
1001      If-Match header  11
1002      If-Modified-Since header  12
1003      If-None-Match header  14
1004
1005
1006
1007Fielding, et al.          Expires July 15, 2008                [Page 18]
1008
1009Internet-Draft              HTTP/1.1, Part 4                January 2008
1010
1011
1012      If-Unmodified-Since header  15
1013
1014   L
1015      Last-Modified header  16
1016
1017   S
1018      Status Codes
1019         304 Not Modified  5
1020         412 Precondition Failed  6
1021
1022
1023Authors' Addresses
1024
1025   Roy T. Fielding (editor)
1026   Day Software
1027   23 Corporate Plaza DR, Suite 280
1028   Newport Beach, CA  92660
1029   USA
1030
1031   Phone: +1-949-706-5300
1032   Fax:   +1-949-706-5305
1033   Email: fielding@gbiv.com
1034   URI:   http://roy.gbiv.com/
1035
1036
1037   Jim Gettys
1038   One Laptop per Child
1039   21 Oak Knoll Road
1040   Carlisle, MA  01741
1041   USA
1042
1043   Email: jg@laptop.org
1044   URI:   http://www.laptop.org/
1045
1046
1047   Jeffrey C. Mogul
1048   Hewlett-Packard Company
1049   HP Labs, Large Scale Systems Group
1050   1501 Page Mill Road, MS 1177
1051   Palo Alto, CA  94304
1052   USA
1053
1054   Email: JeffMogul@acm.org
1055
1056
1057
1058
1059
1060
1061
1062
1063Fielding, et al.          Expires July 15, 2008                [Page 19]
1064
1065Internet-Draft              HTTP/1.1, Part 4                January 2008
1066
1067
1068   Henrik Frystyk Nielsen
1069   Microsoft Corporation
1070   1 Microsoft Way
1071   Redmond, WA  98052
1072   USA
1073
1074   Email: henrikn@microsoft.com
1075
1076
1077   Larry Masinter
1078   Adobe Systems, Incorporated
1079   345 Park Ave
1080   San Jose, CA  95110
1081   USA
1082
1083   Email: LMM@acm.org
1084   URI:   http://larry.masinter.net/
1085
1086
1087   Paul J. Leach
1088   Microsoft Corporation
1089   1 Microsoft Way
1090   Redmond, WA  98052
1091
1092   Email: paulle@microsoft.com
1093
1094
1095   Tim Berners-Lee
1096   World Wide Web Consortium
1097   MIT Computer Science and Artificial Intelligence Laboratory
1098   The Stata Center, Building 32
1099   32 Vassar Street
1100   Cambridge, MA  02139
1101   USA
1102
1103   Email: timbl@w3.org
1104   URI:   http://www.w3.org/People/Berners-Lee/
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119Fielding, et al.          Expires July 15, 2008                [Page 20]
1120
1121Internet-Draft              HTTP/1.1, Part 4                January 2008
1122
1123
1124   Yves Lafon (editor)
1125   World Wide Web Consortium
1126   W3C / ERCIM
1127   2004, rte des Lucioles
1128   Sophia-Antipolis, AM  06902
1129   France
1130
1131   Email: ylafon@w3.org
1132   URI:   http://www.raubacapeu.net/people/yves/
1133
1134
1135   Julian F. Reschke (editor)
1136   greenbytes GmbH
1137   Hafenweg 16
1138   Muenster, NW  48155
1139   Germany
1140
1141   Phone: +49 251 2807760
1142   Fax:   +49 251 2807761
1143   Email: julian.reschke@greenbytes.de
1144   URI:   http://greenbytes.de/tech/webdav/
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175Fielding, et al.          Expires July 15, 2008                [Page 21]
1176
1177Internet-Draft              HTTP/1.1, Part 4                January 2008
1178
1179
1180Full Copyright Statement
1181
1182   Copyright (C) The IETF Trust (2008).
1183
1184   This document is subject to the rights, licenses and restrictions
1185   contained in BCP 78, and except as set forth therein, the authors
1186   retain all their rights.
1187
1188   This document and the information contained herein are provided on an
1189   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1190   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
1191   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
1192   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1193   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1194   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1195
1196
1197Intellectual Property
1198
1199   The IETF takes no position regarding the validity or scope of any
1200   Intellectual Property Rights or other rights that might be claimed to
1201   pertain to the implementation or use of the technology described in
1202   this document or the extent to which any license under such rights
1203   might or might not be available; nor does it represent that it has
1204   made any independent effort to identify any such rights.  Information
1205   on the procedures with respect to rights in RFC documents can be
1206   found in BCP 78 and BCP 79.
1207
1208   Copies of IPR disclosures made to the IETF Secretariat and any
1209   assurances of licenses to be made available, or the result of an
1210   attempt made to obtain a general license or permission for the use of
1211   such proprietary rights by implementers or users of this
1212   specification can be obtained from the IETF on-line IPR repository at
1213   http://www.ietf.org/ipr.
1214
1215   The IETF invites any interested party to bring to its attention any
1216   copyrights, patents or patent applications, or other proprietary
1217   rights that may cover technology that may be required to implement
1218   this standard.  Please address the information to the IETF at
1219   ietf-ipr@ietf.org.
1220
1221
1222Acknowledgment
1223
1224   Funding for the RFC Editor function is provided by the IETF
1225   Administrative Support Activity (IASA).
1226
1227
1228
1229
1230
1231Fielding, et al.          Expires July 15, 2008                [Page 22]
1232
Note: See TracBrowser for help on using the repository browser.