1 | |
---|
2 | |
---|
3 | |
---|
4 | HTTPbis Working Group R. Fielding, Ed. |
---|
5 | Internet-Draft Adobe |
---|
6 | Obsoletes: 2616 (if approved) Y. Lafon, Ed. |
---|
7 | Intended status: Standards Track W3C |
---|
8 | Expires: January 17, 2013 J. Reschke, Ed. |
---|
9 | greenbytes |
---|
10 | July 16, 2012 |
---|
11 | |
---|
12 | |
---|
13 | HTTP/1.1, part 4: Conditional Requests |
---|
14 | draft-ietf-httpbis-p4-conditional-20 |
---|
15 | |
---|
16 | Abstract |
---|
17 | |
---|
18 | The Hypertext Transfer Protocol (HTTP) is an application-level |
---|
19 | protocol for distributed, collaborative, hypertext information |
---|
20 | systems. This document defines HTTP/1.1 conditional requests, |
---|
21 | including metadata header fields for indicating state changes, |
---|
22 | request header fields for making preconditions on such state, and |
---|
23 | rules for constructing the responses to a conditional request when |
---|
24 | one or more preconditions evaluate to false. |
---|
25 | |
---|
26 | Editorial Note (To be removed by RFC Editor) |
---|
27 | |
---|
28 | Discussion of this draft takes place on the HTTPBIS working group |
---|
29 | mailing list (ietf-http-wg@w3.org), which is archived at |
---|
30 | <http://lists.w3.org/Archives/Public/ietf-http-wg/>. |
---|
31 | |
---|
32 | The current issues list is at |
---|
33 | <http://tools.ietf.org/wg/httpbis/trac/report/3> and related |
---|
34 | documents (including fancy diffs) can be found at |
---|
35 | <http://tools.ietf.org/wg/httpbis/>. |
---|
36 | |
---|
37 | The changes in this draft are summarized in Appendix D.1. |
---|
38 | |
---|
39 | Status of This Memo |
---|
40 | |
---|
41 | This Internet-Draft is submitted in full conformance with the |
---|
42 | provisions of BCP 78 and BCP 79. |
---|
43 | |
---|
44 | Internet-Drafts are working documents of the Internet Engineering |
---|
45 | Task Force (IETF). Note that other groups may also distribute |
---|
46 | working documents as Internet-Drafts. The list of current Internet- |
---|
47 | Drafts is at http://datatracker.ietf.org/drafts/current/. |
---|
48 | |
---|
49 | Internet-Drafts are draft documents valid for a maximum of six months |
---|
50 | and may be updated, replaced, or obsoleted by other documents at any |
---|
51 | time. It is inappropriate to use Internet-Drafts as reference |
---|
52 | |
---|
53 | |
---|
54 | |
---|
55 | Fielding, et al. Expires January 17, 2013 [Page 1] |
---|
56 | |
---|
57 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
58 | |
---|
59 | |
---|
60 | material or to cite them other than as "work in progress." |
---|
61 | |
---|
62 | This Internet-Draft will expire on January 17, 2013. |
---|
63 | |
---|
64 | Copyright Notice |
---|
65 | |
---|
66 | Copyright (c) 2012 IETF Trust and the persons identified as the |
---|
67 | document authors. All rights reserved. |
---|
68 | |
---|
69 | This document is subject to BCP 78 and the IETF Trust's Legal |
---|
70 | Provisions Relating to IETF Documents |
---|
71 | (http://trustee.ietf.org/license-info) in effect on the date of |
---|
72 | publication of this document. Please review these documents |
---|
73 | carefully, as they describe your rights and restrictions with respect |
---|
74 | to this document. Code Components extracted from this document must |
---|
75 | include Simplified BSD License text as described in Section 4.e of |
---|
76 | the Trust Legal Provisions and are provided without warranty as |
---|
77 | described in the Simplified BSD License. |
---|
78 | |
---|
79 | This document may contain material from IETF Documents or IETF |
---|
80 | Contributions published or made publicly available before November |
---|
81 | 10, 2008. The person(s) controlling the copyright in some of this |
---|
82 | material may not have granted the IETF Trust the right to allow |
---|
83 | modifications of such material outside the IETF Standards Process. |
---|
84 | Without obtaining an adequate license from the person(s) controlling |
---|
85 | the copyright in such materials, this document may not be modified |
---|
86 | outside the IETF Standards Process, and derivative works of it may |
---|
87 | not be created outside the IETF Standards Process, except to format |
---|
88 | it for publication as an RFC or to translate it into languages other |
---|
89 | than English. |
---|
90 | |
---|
91 | |
---|
92 | |
---|
93 | |
---|
94 | |
---|
95 | |
---|
96 | |
---|
97 | |
---|
98 | |
---|
99 | |
---|
100 | |
---|
101 | |
---|
102 | |
---|
103 | |
---|
104 | |
---|
105 | |
---|
106 | |
---|
107 | |
---|
108 | |
---|
109 | |
---|
110 | |
---|
111 | Fielding, et al. Expires January 17, 2013 [Page 2] |
---|
112 | |
---|
113 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
114 | |
---|
115 | |
---|
116 | Table of Contents |
---|
117 | |
---|
118 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 |
---|
119 | 1.1. Conformance and Error Handling . . . . . . . . . . . . . . 4 |
---|
120 | 1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 |
---|
121 | 2. Validators . . . . . . . . . . . . . . . . . . . . . . . . . . 5 |
---|
122 | 2.1. Weak versus Strong . . . . . . . . . . . . . . . . . . . . 6 |
---|
123 | 2.2. Last-Modified . . . . . . . . . . . . . . . . . . . . . . 7 |
---|
124 | 2.2.1. Generation . . . . . . . . . . . . . . . . . . . . . . 8 |
---|
125 | 2.2.2. Comparison . . . . . . . . . . . . . . . . . . . . . . 8 |
---|
126 | 2.3. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 |
---|
127 | 2.3.1. Generation . . . . . . . . . . . . . . . . . . . . . . 10 |
---|
128 | 2.3.2. Comparison . . . . . . . . . . . . . . . . . . . . . . 11 |
---|
129 | 2.3.3. Example: Entity-tags varying on Content-Negotiated |
---|
130 | Resources . . . . . . . . . . . . . . . . . . . . . . 11 |
---|
131 | 2.4. Rules for When to Use Entity-tags and Last-Modified |
---|
132 | Dates . . . . . . . . . . . . . . . . . . . . . . . . . . 12 |
---|
133 | 3. Precondition Header Fields . . . . . . . . . . . . . . . . . . 14 |
---|
134 | 3.1. If-Match . . . . . . . . . . . . . . . . . . . . . . . . . 14 |
---|
135 | 3.2. If-None-Match . . . . . . . . . . . . . . . . . . . . . . 15 |
---|
136 | 3.3. If-Modified-Since . . . . . . . . . . . . . . . . . . . . 16 |
---|
137 | 3.4. If-Unmodified-Since . . . . . . . . . . . . . . . . . . . 17 |
---|
138 | 3.5. If-Range . . . . . . . . . . . . . . . . . . . . . . . . . 18 |
---|
139 | 4. Status Code Definitions . . . . . . . . . . . . . . . . . . . 18 |
---|
140 | 4.1. 304 Not Modified . . . . . . . . . . . . . . . . . . . . . 18 |
---|
141 | 4.2. 412 Precondition Failed . . . . . . . . . . . . . . . . . 19 |
---|
142 | 5. Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . 19 |
---|
143 | 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 |
---|
144 | 6.1. Status Code Registration . . . . . . . . . . . . . . . . . 20 |
---|
145 | 6.2. Header Field Registration . . . . . . . . . . . . . . . . 21 |
---|
146 | 7. Security Considerations . . . . . . . . . . . . . . . . . . . 21 |
---|
147 | 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 |
---|
148 | 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 |
---|
149 | 9.1. Normative References . . . . . . . . . . . . . . . . . . . 22 |
---|
150 | 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 |
---|
151 | Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 22 |
---|
152 | Appendix B. Imported ABNF . . . . . . . . . . . . . . . . . . . . 23 |
---|
153 | Appendix C. Collected ABNF . . . . . . . . . . . . . . . . . . . 23 |
---|
154 | Appendix D. Change Log (to be removed by RFC Editor before |
---|
155 | publication) . . . . . . . . . . . . . . . . . . . . 24 |
---|
156 | D.1. Since draft-ietf-httpbis-p4-conditional-19 . . . . . . . . 24 |
---|
157 | Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 |
---|
158 | |
---|
159 | |
---|
160 | |
---|
161 | |
---|
162 | |
---|
163 | |
---|
164 | |
---|
165 | |
---|
166 | |
---|
167 | Fielding, et al. Expires January 17, 2013 [Page 3] |
---|
168 | |
---|
169 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
170 | |
---|
171 | |
---|
172 | 1. Introduction |
---|
173 | |
---|
174 | Conditional requests are HTTP requests [Part2] that include one or |
---|
175 | more header fields indicating a precondition to be tested before |
---|
176 | applying the method semantics to the target resource. Each |
---|
177 | precondition is based on metadata that is expected to change if the |
---|
178 | selected representation of the target resource is changed. This |
---|
179 | document defines the HTTP/1.1 conditional request mechanisms in terms |
---|
180 | of the architecture, syntax notation, and conformance criteria |
---|
181 | defined in [Part1]. |
---|
182 | |
---|
183 | Conditional GET requests are the most efficient mechanism for HTTP |
---|
184 | cache updates [Part6]. Conditionals can also be applied to state- |
---|
185 | changing methods, such as PUT and DELETE, to prevent the "lost |
---|
186 | update" problem: one client accidentally overwriting the work of |
---|
187 | another client that has been acting in parallel. |
---|
188 | |
---|
189 | Conditional request preconditions are based on the state of the |
---|
190 | target resource as a whole (its current value set) or the state as |
---|
191 | observed in a previously obtained representation (one value in that |
---|
192 | set). A resource might have multiple current representations, each |
---|
193 | with its own observable state. The conditional request mechanisms |
---|
194 | assume that the mapping of requests to corresponding representations |
---|
195 | will be consistent over time if the server intends to take advantage |
---|
196 | of conditionals. Regardless, if the mapping is inconsistent and the |
---|
197 | server is unable to select the appropriate representation, then no |
---|
198 | harm will result when the precondition evaluates to false. |
---|
199 | |
---|
200 | We use the term "selected representation" to refer to the current |
---|
201 | representation of the target resource that would have been selected |
---|
202 | in a successful response if the same request had used the method GET |
---|
203 | and had excluded all of the conditional request header fields. The |
---|
204 | conditional request preconditions are evaluated by comparing the |
---|
205 | values provided in the request header fields to the current metadata |
---|
206 | for the selected representation. |
---|
207 | |
---|
208 | 1.1. Conformance and Error Handling |
---|
209 | |
---|
210 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
---|
211 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
---|
212 | document are to be interpreted as described in [RFC2119]. |
---|
213 | |
---|
214 | This specification targets conformance criteria according to the role |
---|
215 | of a participant in HTTP communication. Hence, HTTP requirements are |
---|
216 | placed on senders, recipients, clients, servers, user agents, |
---|
217 | intermediaries, origin servers, proxies, gateways, or caches, |
---|
218 | depending on what behavior is being constrained by the requirement. |
---|
219 | See Section 2 of [Part1] for definitions of these terms. |
---|
220 | |
---|
221 | |
---|
222 | |
---|
223 | Fielding, et al. Expires January 17, 2013 [Page 4] |
---|
224 | |
---|
225 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
226 | |
---|
227 | |
---|
228 | The verb "generate" is used instead of "send" where a requirement |
---|
229 | differentiates between creating a protocol element and merely |
---|
230 | forwarding a received element downstream. |
---|
231 | |
---|
232 | An implementation is considered conformant if it complies with all of |
---|
233 | the requirements associated with the roles it partakes in HTTP. Note |
---|
234 | that SHOULD-level requirements are relevant here, unless one of the |
---|
235 | documented exceptions is applicable. |
---|
236 | |
---|
237 | This document also uses ABNF to define valid protocol elements |
---|
238 | (Section 1.2). In addition to the prose requirements placed upon |
---|
239 | them, senders MUST NOT generate protocol elements that do not match |
---|
240 | the grammar defined by the ABNF rules for those protocol elements |
---|
241 | that are applicable to the sender's role. If a received protocol |
---|
242 | element is processed, the recipient MUST be able to parse any value |
---|
243 | that would match the ABNF rules for that protocol element, excluding |
---|
244 | only those rules not applicable to the recipient's role. |
---|
245 | |
---|
246 | Unless noted otherwise, a recipient MAY attempt to recover a usable |
---|
247 | protocol element from an invalid construct. HTTP does not define |
---|
248 | specific error handling mechanisms except when they have a direct |
---|
249 | impact on security, since different applications of the protocol |
---|
250 | require different error handling strategies. For example, a Web |
---|
251 | browser might wish to transparently recover from a response where the |
---|
252 | Location header field doesn't parse according to the ABNF, whereas a |
---|
253 | systems control client might consider any form of error recovery to |
---|
254 | be dangerous. |
---|
255 | |
---|
256 | 1.2. Syntax Notation |
---|
257 | |
---|
258 | This specification uses the Augmented Backus-Naur Form (ABNF) |
---|
259 | notation of [RFC5234] with the list rule extension defined in Section |
---|
260 | 1.2 of [Part1]. Appendix B describes rules imported from other |
---|
261 | documents. Appendix C shows the collected ABNF with the list rule |
---|
262 | expanded. |
---|
263 | |
---|
264 | 2. Validators |
---|
265 | |
---|
266 | This specification defines two forms of metadata that are commonly |
---|
267 | used to observe resource state and test for preconditions: |
---|
268 | modification dates (Section 2.2) and opaque entity tags |
---|
269 | (Section 2.3). Additional metadata that reflects resource state has |
---|
270 | been defined by various extensions of HTTP, such as WebDAV [RFC4918], |
---|
271 | that are beyond the scope of this specification. A resource metadata |
---|
272 | value is referred to as a "validator" when it is used within a |
---|
273 | precondition. |
---|
274 | |
---|
275 | |
---|
276 | |
---|
277 | |
---|
278 | |
---|
279 | Fielding, et al. Expires January 17, 2013 [Page 5] |
---|
280 | |
---|
281 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
282 | |
---|
283 | |
---|
284 | 2.1. Weak versus Strong |
---|
285 | |
---|
286 | Validators come in two flavors: strong or weak. Weak validators are |
---|
287 | easy to generate but are far less useful for comparisons. Strong |
---|
288 | validators are ideal for comparisons but can be very difficult (and |
---|
289 | occasionally impossible) to generate efficiently. Rather than impose |
---|
290 | that all forms of resource adhere to the same strength of validator, |
---|
291 | HTTP exposes the type of validator in use and imposes restrictions on |
---|
292 | when weak validators can be used as preconditions. |
---|
293 | |
---|
294 | A "strong validator" is a representation metadata value that MUST be |
---|
295 | changed to a new, previously unused or guaranteed unique, value |
---|
296 | whenever a change occurs to the representation data such that a |
---|
297 | change would be observable in the payload body of a 200 (OK) response |
---|
298 | to GET. |
---|
299 | |
---|
300 | A strong validator MAY be changed for other reasons, such as when a |
---|
301 | semantically significant part of the representation metadata is |
---|
302 | changed (e.g., Content-Type), but it is in the best interests of the |
---|
303 | origin server to only change the value when it is necessary to |
---|
304 | invalidate the stored responses held by remote caches and authoring |
---|
305 | tools. A strong validator MUST be unique across all representations |
---|
306 | of a given resource, such that no two representations of that |
---|
307 | resource share the same validator unless their payload body would be |
---|
308 | identical. |
---|
309 | |
---|
310 | Cache entries might persist for arbitrarily long periods, regardless |
---|
311 | of expiration times. Thus, a cache might attempt to validate an |
---|
312 | entry using a validator that it obtained in the distant past. A |
---|
313 | strong validator MUST be unique across all versions of all |
---|
314 | representations associated with a particular resource over time. |
---|
315 | However, there is no implication of uniqueness across representations |
---|
316 | of different resources (i.e., the same strong validator might be in |
---|
317 | use for representations of multiple resources at the same time and |
---|
318 | does not imply that those representations are equivalent). |
---|
319 | |
---|
320 | There are a variety of strong validators used in practice. The best |
---|
321 | are based on strict revision control, wherein each change to a |
---|
322 | representation always results in a unique node name and revision |
---|
323 | identifier being assigned before the representation is made |
---|
324 | accessible to GET. A collision-resistant hash function applied to |
---|
325 | the representation data is also sufficient if the data is available |
---|
326 | prior to the response header fields being sent and the digest does |
---|
327 | not need to be recalculated every time a validation request is |
---|
328 | received. However, if a resource has distinct representations that |
---|
329 | differ only in their metadata, such as might occur with content |
---|
330 | negotiation over media types that happen to share the same data |
---|
331 | format, then the origin server SHOULD incorporate additional |
---|
332 | |
---|
333 | |
---|
334 | |
---|
335 | Fielding, et al. Expires January 17, 2013 [Page 6] |
---|
336 | |
---|
337 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
338 | |
---|
339 | |
---|
340 | information in the validator to distinguish those representations and |
---|
341 | avoid confusing cache behavior. |
---|
342 | |
---|
343 | In contrast, a "weak validator" is a representation metadata value |
---|
344 | that might not be changed for every change to the representation |
---|
345 | data. This weakness might be due to limitations in how the value is |
---|
346 | calculated, such as clock resolution or an inability to ensure |
---|
347 | uniqueness for all possible representations of the resource, or due |
---|
348 | to a desire by the resource owner to group representations by some |
---|
349 | self-determined set of equivalency rather than unique sequences of |
---|
350 | data. An origin server SHOULD change a weak entity-tag whenever it |
---|
351 | considers prior representations to be unacceptable as a substitute |
---|
352 | for the current representation. In other words, a weak entity-tag |
---|
353 | ought to change whenever the origin server wants caches to invalidate |
---|
354 | old responses. |
---|
355 | |
---|
356 | For example, the representation of a weather report that changes in |
---|
357 | content every second, based on dynamic measurements, might be grouped |
---|
358 | into sets of equivalent representations (from the origin server's |
---|
359 | perspective) with the same weak validator in order to allow cached |
---|
360 | representations to be valid for a reasonable period of time (perhaps |
---|
361 | adjusted dynamically based on server load or weather quality). |
---|
362 | Likewise, a representation's modification time, if defined with only |
---|
363 | one-second resolution, might be a weak validator if it is possible |
---|
364 | for the representation to be modified twice during a single second |
---|
365 | and retrieved between those modifications. |
---|
366 | |
---|
367 | A "use" of a validator occurs when either a client generates a |
---|
368 | request and includes the validator in a precondition or when a server |
---|
369 | compares two validators. Weak validators are only usable in contexts |
---|
370 | that do not depend on exact equality of a representation's payload |
---|
371 | body. Strong validators are usable and preferred for all conditional |
---|
372 | requests, including cache validation, partial content ranges, and |
---|
373 | "lost update" avoidance. |
---|
374 | |
---|
375 | 2.2. Last-Modified |
---|
376 | |
---|
377 | The "Last-Modified" header field indicates the date and time at which |
---|
378 | the origin server believes the selected representation was last |
---|
379 | modified. |
---|
380 | |
---|
381 | Last-Modified = HTTP-date |
---|
382 | |
---|
383 | An example of its use is |
---|
384 | |
---|
385 | Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT |
---|
386 | |
---|
387 | |
---|
388 | |
---|
389 | |
---|
390 | |
---|
391 | Fielding, et al. Expires January 17, 2013 [Page 7] |
---|
392 | |
---|
393 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
394 | |
---|
395 | |
---|
396 | 2.2.1. Generation |
---|
397 | |
---|
398 | Origin servers SHOULD send Last-Modified for any selected |
---|
399 | representation for which a last modification date can be reasonably |
---|
400 | and consistently determined, since its use in conditional requests |
---|
401 | and evaluating cache freshness ([Part6]) results in a substantial |
---|
402 | reduction of HTTP traffic on the Internet and can be a significant |
---|
403 | factor in improving service scalability and reliability. |
---|
404 | |
---|
405 | A representation is typically the sum of many parts behind the |
---|
406 | resource interface. The last-modified time would usually be the most |
---|
407 | recent time that any of those parts were changed. How that value is |
---|
408 | determined for any given resource is an implementation detail beyond |
---|
409 | the scope of this specification. What matters to HTTP is how |
---|
410 | recipients of the Last-Modified header field can use its value to |
---|
411 | make conditional requests and test the validity of locally cached |
---|
412 | responses. |
---|
413 | |
---|
414 | An origin server SHOULD obtain the Last-Modified value of the |
---|
415 | representation as close as possible to the time that it generates the |
---|
416 | Date field value for its response. This allows a recipient to make |
---|
417 | an accurate assessment of the representation's modification time, |
---|
418 | especially if the representation changes near the time that the |
---|
419 | response is generated. |
---|
420 | |
---|
421 | An origin server with a clock MUST NOT send a Last-Modified date that |
---|
422 | is later than the server's time of message origination (Date). If |
---|
423 | the last modification time is derived from implementation-specific |
---|
424 | metadata that evaluates to some time in the future, according to the |
---|
425 | origin server's clock, then the origin server MUST replace that value |
---|
426 | with the message origination date. This prevents a future |
---|
427 | modification date from having an adverse impact on cache validation. |
---|
428 | |
---|
429 | An origin server without a clock MUST NOT assign Last-Modified values |
---|
430 | to a response unless these values were associated with the resource |
---|
431 | by some other system or user with a reliable clock. |
---|
432 | |
---|
433 | 2.2.2. Comparison |
---|
434 | |
---|
435 | A Last-Modified time, when used as a validator in a request, is |
---|
436 | implicitly weak unless it is possible to deduce that it is strong, |
---|
437 | using the following rules: |
---|
438 | |
---|
439 | o The validator is being compared by an origin server to the actual |
---|
440 | current validator for the representation and, |
---|
441 | |
---|
442 | o That origin server reliably knows that the associated |
---|
443 | representation did not change twice during the second covered by |
---|
444 | |
---|
445 | |
---|
446 | |
---|
447 | Fielding, et al. Expires January 17, 2013 [Page 8] |
---|
448 | |
---|
449 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
450 | |
---|
451 | |
---|
452 | the presented validator. |
---|
453 | |
---|
454 | or |
---|
455 | |
---|
456 | o The validator is about to be used by a client in an If-Modified- |
---|
457 | Since, If-Unmodified-Since header field, because the client has a |
---|
458 | cache entry, or If-Range for the associated representation, and |
---|
459 | |
---|
460 | o That cache entry includes a Date value, which gives the time when |
---|
461 | the origin server sent the original response, and |
---|
462 | |
---|
463 | o The presented Last-Modified time is at least 60 seconds before the |
---|
464 | Date value. |
---|
465 | |
---|
466 | or |
---|
467 | |
---|
468 | o The validator is being compared by an intermediate cache to the |
---|
469 | validator stored in its cache entry for the representation, and |
---|
470 | |
---|
471 | o That cache entry includes a Date value, which gives the time when |
---|
472 | the origin server sent the original response, and |
---|
473 | |
---|
474 | o The presented Last-Modified time is at least 60 seconds before the |
---|
475 | Date value. |
---|
476 | |
---|
477 | This method relies on the fact that if two different responses were |
---|
478 | sent by the origin server during the same second, but both had the |
---|
479 | same Last-Modified time, then at least one of those responses would |
---|
480 | have a Date value equal to its Last-Modified time. The arbitrary 60- |
---|
481 | second limit guards against the possibility that the Date and Last- |
---|
482 | Modified values are generated from different clocks, or at somewhat |
---|
483 | different times during the preparation of the response. An |
---|
484 | implementation MAY use a value larger than 60 seconds, if it is |
---|
485 | believed that 60 seconds is too short. |
---|
486 | |
---|
487 | 2.3. ETag |
---|
488 | |
---|
489 | The "ETag" header field provides the current entity-tag for the |
---|
490 | selected representation. An entity-tag is an opaque validator for |
---|
491 | differentiating between multiple representations of the same |
---|
492 | resource, regardless of whether those multiple representations are |
---|
493 | due to resource state changes over time, content negotiation |
---|
494 | resulting in multiple representations being valid at the same time, |
---|
495 | or both. An entity-tag consists of an opaque quoted string, possibly |
---|
496 | prefixed by a weakness indicator. |
---|
497 | |
---|
498 | |
---|
499 | |
---|
500 | |
---|
501 | |
---|
502 | |
---|
503 | Fielding, et al. Expires January 17, 2013 [Page 9] |
---|
504 | |
---|
505 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
506 | |
---|
507 | |
---|
508 | ETag = entity-tag |
---|
509 | |
---|
510 | entity-tag = [ weak ] opaque-tag |
---|
511 | weak = %x57.2F ; "W/", case-sensitive |
---|
512 | opaque-tag = DQUOTE *etagc DQUOTE |
---|
513 | etagc = %x21 / %x23-7E / obs-text |
---|
514 | ; VCHAR except double quotes, plus obs-text |
---|
515 | |
---|
516 | Note: Previously, opaque-tag was defined to be a quoted-string |
---|
517 | ([RFC2616], Section 3.11), thus some recipients might perform |
---|
518 | backslash unescaping. Servers therefore ought to avoid backslash |
---|
519 | characters in entity tags. |
---|
520 | |
---|
521 | An entity-tag can be more reliable for validation than a modification |
---|
522 | date in situations where it is inconvenient to store modification |
---|
523 | dates, where the one-second resolution of HTTP date values is not |
---|
524 | sufficient, or where modification dates are not consistently |
---|
525 | maintained. |
---|
526 | |
---|
527 | Examples: |
---|
528 | |
---|
529 | ETag: "xyzzy" |
---|
530 | ETag: W/"xyzzy" |
---|
531 | ETag: "" |
---|
532 | |
---|
533 | An entity-tag can be either a weak or strong validator, with strong |
---|
534 | being the default. If an origin server provides an entity-tag for a |
---|
535 | representation and the generation of that entity-tag does not satisfy |
---|
536 | the requirements for a strong validator (Section 2.1), then that |
---|
537 | entity-tag MUST be marked as weak by prefixing its opaque value with |
---|
538 | "W/" (case-sensitive). |
---|
539 | |
---|
540 | 2.3.1. Generation |
---|
541 | |
---|
542 | The principle behind entity-tags is that only the service author |
---|
543 | knows the implementation of a resource well enough to select the most |
---|
544 | accurate and efficient validation mechanism for that resource, and |
---|
545 | that any such mechanism can be mapped to a simple sequence of octets |
---|
546 | for easy comparison. Since the value is opaque, there is no need for |
---|
547 | the client to be aware of how each entity-tag is constructed. |
---|
548 | |
---|
549 | For example, a resource that has implementation-specific versioning |
---|
550 | applied to all changes might use an internal revision number, perhaps |
---|
551 | combined with a variance identifier for content negotiation, to |
---|
552 | accurately differentiate between representations. Other |
---|
553 | implementations might use a collision-resistant hash of |
---|
554 | representation content, a combination of various filesystem |
---|
555 | attributes, or a modification timestamp that has sub-second |
---|
556 | |
---|
557 | |
---|
558 | |
---|
559 | Fielding, et al. Expires January 17, 2013 [Page 10] |
---|
560 | |
---|
561 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
562 | |
---|
563 | |
---|
564 | resolution. |
---|
565 | |
---|
566 | Origin servers SHOULD send ETag for any selected representation for |
---|
567 | which detection of changes can be reasonably and consistently |
---|
568 | determined, since the entity-tag's use in conditional requests and |
---|
569 | evaluating cache freshness ([Part6]) can result in a substantial |
---|
570 | reduction of HTTP network traffic and can be a significant factor in |
---|
571 | improving service scalability and reliability. |
---|
572 | |
---|
573 | 2.3.2. Comparison |
---|
574 | |
---|
575 | There are two entity-tag comparison functions, depending on whether |
---|
576 | the comparison context allows the use of weak validators or not: |
---|
577 | |
---|
578 | o The strong comparison function: in order to be considered equal, |
---|
579 | both opaque-tags MUST be identical character-by-character, and |
---|
580 | both MUST NOT be weak. |
---|
581 | |
---|
582 | o The weak comparison function: in order to be considered equal, |
---|
583 | both opaque-tags MUST be identical character-by-character, but |
---|
584 | either or both of them MAY be tagged as "weak" without affecting |
---|
585 | the result. |
---|
586 | |
---|
587 | The example below shows the results for a set of entity-tag pairs, |
---|
588 | and both the weak and strong comparison function results: |
---|
589 | |
---|
590 | +--------+--------+-------------------+-----------------+ |
---|
591 | | ETag 1 | ETag 2 | Strong Comparison | Weak Comparison | |
---|
592 | +--------+--------+-------------------+-----------------+ |
---|
593 | | W/"1" | W/"1" | no match | match | |
---|
594 | | W/"1" | W/"2" | no match | no match | |
---|
595 | | W/"1" | "1" | no match | match | |
---|
596 | | "1" | "1" | match | match | |
---|
597 | +--------+--------+-------------------+-----------------+ |
---|
598 | |
---|
599 | 2.3.3. Example: Entity-tags varying on Content-Negotiated Resources |
---|
600 | |
---|
601 | Consider a resource that is subject to content negotiation (Section 8 |
---|
602 | of [Part2]), and where the representations returned upon a GET |
---|
603 | request vary based on the Accept-Encoding request header field |
---|
604 | (Section 9.3 of [Part2]): |
---|
605 | |
---|
606 | >> Request: |
---|
607 | |
---|
608 | GET /index HTTP/1.1 |
---|
609 | Host: www.example.com |
---|
610 | Accept-Encoding: gzip |
---|
611 | |
---|
612 | |
---|
613 | |
---|
614 | |
---|
615 | Fielding, et al. Expires January 17, 2013 [Page 11] |
---|
616 | |
---|
617 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
618 | |
---|
619 | |
---|
620 | In this case, the response might or might not use the gzip content |
---|
621 | coding. If it does not, the response might look like: |
---|
622 | |
---|
623 | >> Response: |
---|
624 | |
---|
625 | HTTP/1.1 200 OK |
---|
626 | Date: Thu, 26 Mar 2010 00:05:00 GMT |
---|
627 | ETag: "123-a" |
---|
628 | Content-Length: 70 |
---|
629 | Vary: Accept-Encoding |
---|
630 | Content-Type: text/plain |
---|
631 | |
---|
632 | Hello World! |
---|
633 | Hello World! |
---|
634 | Hello World! |
---|
635 | Hello World! |
---|
636 | Hello World! |
---|
637 | |
---|
638 | An alternative representation that does use gzip content coding would |
---|
639 | be: |
---|
640 | |
---|
641 | >> Response: |
---|
642 | |
---|
643 | HTTP/1.1 200 OK |
---|
644 | Date: Thu, 26 Mar 2010 00:05:00 GMT |
---|
645 | ETag: "123-b" |
---|
646 | Content-Length: 43 |
---|
647 | Vary: Accept-Encoding |
---|
648 | Content-Type: text/plain |
---|
649 | Content-Encoding: gzip |
---|
650 | |
---|
651 | ...binary data... |
---|
652 | |
---|
653 | Note: Content codings are a property of the representation, so |
---|
654 | therefore an entity-tag of an encoded representation has to be |
---|
655 | distinct from an unencoded representation to prevent conflicts |
---|
656 | during cache updates and range requests. In contrast, transfer |
---|
657 | codings (Section 4 of [Part1]) apply only during message transfer |
---|
658 | and do not require distinct entity-tags. |
---|
659 | |
---|
660 | 2.4. Rules for When to Use Entity-tags and Last-Modified Dates |
---|
661 | |
---|
662 | We adopt a set of rules and recommendations for origin servers, |
---|
663 | clients, and caches regarding when various validator types ought to |
---|
664 | be used, and for what purposes. |
---|
665 | |
---|
666 | HTTP/1.1 origin servers: |
---|
667 | |
---|
668 | |
---|
669 | |
---|
670 | |
---|
671 | Fielding, et al. Expires January 17, 2013 [Page 12] |
---|
672 | |
---|
673 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
674 | |
---|
675 | |
---|
676 | o SHOULD send an entity-tag validator unless it is not feasible to |
---|
677 | generate one. |
---|
678 | |
---|
679 | o MAY send a weak entity-tag instead of a strong entity-tag, if |
---|
680 | performance considerations support the use of weak entity-tags, or |
---|
681 | if it is unfeasible to send a strong entity-tag. |
---|
682 | |
---|
683 | o SHOULD send a Last-Modified value if it is feasible to send one. |
---|
684 | |
---|
685 | In other words, the preferred behavior for an HTTP/1.1 origin server |
---|
686 | is to send both a strong entity-tag and a Last-Modified value. |
---|
687 | |
---|
688 | HTTP/1.1 clients: |
---|
689 | |
---|
690 | o MUST use that entity-tag in any cache-conditional request (using |
---|
691 | If-Match or If-None-Match) if an entity-tag has been provided by |
---|
692 | the origin server. |
---|
693 | |
---|
694 | o SHOULD use the Last-Modified value in non-subrange cache- |
---|
695 | conditional requests (using If-Modified-Since) if only a Last- |
---|
696 | Modified value has been provided by the origin server. |
---|
697 | |
---|
698 | o MAY use the Last-Modified value in subrange cache-conditional |
---|
699 | requests (using If-Unmodified-Since) if only a Last-Modified value |
---|
700 | has been provided by an HTTP/1.0 origin server. The user agent |
---|
701 | SHOULD provide a way to disable this, in case of difficulty. |
---|
702 | |
---|
703 | o SHOULD use both validators in cache-conditional requests if both |
---|
704 | an entity-tag and a Last-Modified value have been provided by the |
---|
705 | origin server. This allows both HTTP/1.0 and HTTP/1.1 caches to |
---|
706 | respond appropriately. |
---|
707 | |
---|
708 | An HTTP/1.1 origin server, upon receiving a conditional request that |
---|
709 | includes both a Last-Modified date (e.g., in an If-Modified-Since or |
---|
710 | If-Unmodified-Since header field) and one or more entity-tags (e.g., |
---|
711 | in an If-Match, If-None-Match, or If-Range header field) as cache |
---|
712 | validators, MUST NOT return a response status code of 304 (Not |
---|
713 | Modified) unless doing so is consistent with all of the conditional |
---|
714 | header fields in the request. |
---|
715 | |
---|
716 | An HTTP/1.1 caching proxy, upon receiving a conditional request that |
---|
717 | includes both a Last-Modified date and one or more entity-tags as |
---|
718 | cache validators, MUST NOT return a locally cached response to the |
---|
719 | client unless that cached response is consistent with all of the |
---|
720 | conditional header fields in the request. |
---|
721 | |
---|
722 | Note: The general principle behind these rules is that HTTP/1.1 |
---|
723 | servers and clients ought to transmit as much non-redundant |
---|
724 | |
---|
725 | |
---|
726 | |
---|
727 | Fielding, et al. Expires January 17, 2013 [Page 13] |
---|
728 | |
---|
729 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
730 | |
---|
731 | |
---|
732 | information as is available in their responses and requests. |
---|
733 | HTTP/1.1 systems receiving this information will make the most |
---|
734 | conservative assumptions about the validators they receive. |
---|
735 | |
---|
736 | HTTP/1.0 clients and caches might ignore entity-tags. Generally, |
---|
737 | last-modified values received or used by these systems will |
---|
738 | support transparent and efficient caching, and so HTTP/1.1 origin |
---|
739 | servers still ought to provide Last-Modified values. |
---|
740 | |
---|
741 | 3. Precondition Header Fields |
---|
742 | |
---|
743 | This section defines the syntax and semantics of HTTP/1.1 header |
---|
744 | fields for applying preconditions on requests. Section 5 defines the |
---|
745 | order of evaluation when more than one precondition is present in a |
---|
746 | request. |
---|
747 | |
---|
748 | 3.1. If-Match |
---|
749 | |
---|
750 | The "If-Match" header field can be used to make a request method |
---|
751 | conditional on the current existence or value of an entity-tag for |
---|
752 | one or more representations of the target resource. |
---|
753 | |
---|
754 | If-Match is generally useful for resource update requests, such as |
---|
755 | PUT requests, as a means for protecting against accidental overwrites |
---|
756 | when multiple clients are acting in parallel on the same resource |
---|
757 | (i.e., the "lost update" problem). An If-Match field-value of "*" |
---|
758 | places the precondition on the existence of any current |
---|
759 | representation for the target resource. |
---|
760 | |
---|
761 | If-Match = "*" / 1#entity-tag |
---|
762 | |
---|
763 | The If-Match condition is met if and only if any of the entity-tags |
---|
764 | listed in the If-Match field value match the entity-tag of the |
---|
765 | selected representation for the target resource (as per |
---|
766 | Section 2.3.2), or if "*" is given and any current representation |
---|
767 | exists for the target resource. |
---|
768 | |
---|
769 | If the condition is met, the server MAY perform the request method as |
---|
770 | if the If-Match header field was not present. |
---|
771 | |
---|
772 | Origin servers MUST NOT perform the requested method if the condition |
---|
773 | is not met; instead they MUST respond with the 412 (Precondition |
---|
774 | Failed) status code. |
---|
775 | |
---|
776 | Proxy servers using a cached response as the selected representation |
---|
777 | MUST NOT perform the requested method if the condition is not met; |
---|
778 | instead, they MUST forward the request towards the origin server. |
---|
779 | |
---|
780 | |
---|
781 | |
---|
782 | |
---|
783 | Fielding, et al. Expires January 17, 2013 [Page 14] |
---|
784 | |
---|
785 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
786 | |
---|
787 | |
---|
788 | If the request would, without the If-Match header field, result in |
---|
789 | anything other than a 2xx (Successful) or 412 (Precondition Failed) |
---|
790 | status code, then the If-Match header field MUST be ignored. |
---|
791 | |
---|
792 | Examples: |
---|
793 | |
---|
794 | If-Match: "xyzzy" |
---|
795 | If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |
---|
796 | If-Match: * |
---|
797 | |
---|
798 | 3.2. If-None-Match |
---|
799 | |
---|
800 | The "If-None-Match" header field can be used to make a request method |
---|
801 | conditional on not matching any of the current entity-tag values for |
---|
802 | representations of the target resource. |
---|
803 | |
---|
804 | If-None-Match is primarily used in conditional GET requests to enable |
---|
805 | efficient updates of cached information with a minimum amount of |
---|
806 | transaction overhead. A client that has one or more representations |
---|
807 | previously obtained from the target resource can send If-None-Match |
---|
808 | with a list of the associated entity-tags in the hope of receiving a |
---|
809 | 304 (Not Modified) response if at least one of those representations |
---|
810 | matches the selected representation. |
---|
811 | |
---|
812 | If-None-Match can also be used with a value of "*" to prevent an |
---|
813 | unsafe request method (e.g., PUT) from inadvertently modifying an |
---|
814 | existing representation of the target resource when the client |
---|
815 | believes that the resource does not have a current representation. |
---|
816 | This is a variation on the "lost update" problem that might arise if |
---|
817 | more than one client attempts to create an initial representation for |
---|
818 | the target resource. |
---|
819 | |
---|
820 | If-None-Match = "*" / 1#entity-tag |
---|
821 | |
---|
822 | The If-None-Match condition is met if and only if none of the entity- |
---|
823 | tags listed in the If-None-Match field value match the entity-tag of |
---|
824 | the selected representation for the target resource (as per |
---|
825 | Section 2.3.2), or if "*" is given and no current representation |
---|
826 | exists for that resource. |
---|
827 | |
---|
828 | If the condition is not met, the server MUST NOT perform the |
---|
829 | requested method. Instead, if the request method was GET or HEAD, |
---|
830 | the server SHOULD respond with a 304 (Not Modified) status code, |
---|
831 | including the cache-related header fields (particularly ETag) of the |
---|
832 | selected representation that has a matching entity-tag. For all |
---|
833 | other request methods, the server MUST respond with a 412 |
---|
834 | (Precondition Failed) status code. |
---|
835 | |
---|
836 | |
---|
837 | |
---|
838 | |
---|
839 | Fielding, et al. Expires January 17, 2013 [Page 15] |
---|
840 | |
---|
841 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
842 | |
---|
843 | |
---|
844 | If the condition is met, the server MAY perform the requested method |
---|
845 | as if the If-None-Match header field did not exist, but MUST also |
---|
846 | ignore any If-Modified-Since header field(s) in the request. That |
---|
847 | is, if no entity-tags match, then the server MUST NOT return a 304 |
---|
848 | (Not Modified) response. |
---|
849 | |
---|
850 | If the request would, without the If-None-Match header field, result |
---|
851 | in anything other than a 2xx (Successful) or 304 (Not Modified) |
---|
852 | status code, then the If-None-Match header field MUST be ignored. |
---|
853 | (See Section 2.4 for a discussion of server behavior when both If- |
---|
854 | Modified-Since and If-None-Match appear in the same request.) |
---|
855 | |
---|
856 | Examples: |
---|
857 | |
---|
858 | If-None-Match: "xyzzy" |
---|
859 | If-None-Match: W/"xyzzy" |
---|
860 | If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz" |
---|
861 | If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz" |
---|
862 | If-None-Match: * |
---|
863 | |
---|
864 | 3.3. If-Modified-Since |
---|
865 | |
---|
866 | The "If-Modified-Since" header field can be used with GET or HEAD to |
---|
867 | make the method conditional by modification date: if the selected |
---|
868 | representation has not been modified since the time specified in this |
---|
869 | field, then do not perform the request method; instead, respond as |
---|
870 | detailed below. |
---|
871 | |
---|
872 | If-Modified-Since = HTTP-date |
---|
873 | |
---|
874 | An example of the field is: |
---|
875 | |
---|
876 | If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
---|
877 | |
---|
878 | A GET method with an If-Modified-Since header field and no Range |
---|
879 | header field requests that the selected representation be transferred |
---|
880 | only if it has been modified since the date given by the If-Modified- |
---|
881 | Since header field. The algorithm for determining this includes the |
---|
882 | following cases: |
---|
883 | |
---|
884 | 1. If the request would normally result in anything other than a 200 |
---|
885 | (OK) status code, or if the passed If-Modified-Since date is |
---|
886 | invalid, the response is exactly the same as for a normal GET. A |
---|
887 | date which is later than the server's current time is invalid. |
---|
888 | |
---|
889 | 2. If the selected representation has been modified since the If- |
---|
890 | Modified-Since date, the response is exactly the same as for a |
---|
891 | normal GET. |
---|
892 | |
---|
893 | |
---|
894 | |
---|
895 | Fielding, et al. Expires January 17, 2013 [Page 16] |
---|
896 | |
---|
897 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
898 | |
---|
899 | |
---|
900 | 3. If the selected representation has not been modified since a |
---|
901 | valid If-Modified-Since date, the server SHOULD return a 304 (Not |
---|
902 | Modified) response. |
---|
903 | |
---|
904 | The purpose of this feature is to allow efficient updates of cached |
---|
905 | information with a minimum amount of transaction overhead. |
---|
906 | |
---|
907 | Note: The Range header field modifies the meaning of If-Modified- |
---|
908 | Since; see Section 5.4 of [Part5] for full details. |
---|
909 | |
---|
910 | Note: If-Modified-Since times are interpreted by the server, whose |
---|
911 | clock might not be synchronized with the client. |
---|
912 | |
---|
913 | Note: When handling an If-Modified-Since header field, some |
---|
914 | servers will use an exact date comparison function, rather than a |
---|
915 | less-than function, for deciding whether to send a 304 (Not |
---|
916 | Modified) response. To get best results when sending an If- |
---|
917 | Modified-Since header field for cache validation, clients are |
---|
918 | advised to use the exact date string received in a previous Last- |
---|
919 | Modified header field whenever possible. |
---|
920 | |
---|
921 | Note: If a client uses an arbitrary date in the If-Modified-Since |
---|
922 | header field instead of a date taken from the Last-Modified header |
---|
923 | field for the same request, the client needs to be aware that this |
---|
924 | date is interpreted in the server's understanding of time. |
---|
925 | Unsynchronized clocks and rounding problems, due to the different |
---|
926 | encodings of time between the client and server, are concerns. |
---|
927 | This includes the possibility of race conditions if the document |
---|
928 | has changed between the time it was first requested and the If- |
---|
929 | Modified-Since date of a subsequent request, and the possibility |
---|
930 | of clock-skew-related problems if the If-Modified-Since date is |
---|
931 | derived from the client's clock without correction to the server's |
---|
932 | clock. Corrections for different time bases between client and |
---|
933 | server are at best approximate due to network latency. |
---|
934 | |
---|
935 | 3.4. If-Unmodified-Since |
---|
936 | |
---|
937 | The "If-Unmodified-Since" header field can be used to make a request |
---|
938 | method conditional by modification date: if the selected |
---|
939 | representation has been modified since the time specified in this |
---|
940 | field, then the server MUST NOT perform the requested operation and |
---|
941 | MUST instead respond with the 412 (Precondition Failed) status code. |
---|
942 | If the selected representation has not been modified since the time |
---|
943 | specified in this field, the server SHOULD perform the request method |
---|
944 | as if the If-Unmodified-Since header field were not present. |
---|
945 | |
---|
946 | If-Unmodified-Since = HTTP-date |
---|
947 | |
---|
948 | |
---|
949 | |
---|
950 | |
---|
951 | Fielding, et al. Expires January 17, 2013 [Page 17] |
---|
952 | |
---|
953 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
954 | |
---|
955 | |
---|
956 | An example of the field is: |
---|
957 | |
---|
958 | If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT |
---|
959 | |
---|
960 | If a request normally (i.e., in absence of the If-Unmodified-Since |
---|
961 | header field) would result in anything other than a 2xx (Successful) |
---|
962 | or 412 (Precondition Failed) status code, the If-Unmodified-Since |
---|
963 | header field SHOULD be ignored. |
---|
964 | |
---|
965 | If the specified date is invalid, the header field MUST be ignored. |
---|
966 | |
---|
967 | 3.5. If-Range |
---|
968 | |
---|
969 | The "If-Range" header field provides a special conditional request |
---|
970 | mechanism that is similar to If-Match and If-Unmodified-Since but |
---|
971 | specific to HTTP range requests. If-Range is defined in Section 5.3 |
---|
972 | of [Part5]. |
---|
973 | |
---|
974 | 4. Status Code Definitions |
---|
975 | |
---|
976 | 4.1. 304 Not Modified |
---|
977 | |
---|
978 | The 304 status code indicates that a conditional GET request has been |
---|
979 | received and would have resulted in a 200 (OK) response if it were |
---|
980 | not for the fact that the condition has evaluated to false. In other |
---|
981 | words, there is no need for the server to transfer a representation |
---|
982 | of the target resource because the client's request indicates that it |
---|
983 | already has a valid representation, as indicated by the 304 response |
---|
984 | header fields, and is therefore redirecting the client to make use of |
---|
985 | that stored representation as if it were the payload of a 200 |
---|
986 | response. The 304 response MUST NOT contain a message-body, and thus |
---|
987 | is always terminated by the first empty line after the header fields. |
---|
988 | |
---|
989 | A 304 response MUST include a Date header field (Section 9.10 of |
---|
990 | [Part2]) unless the origin server does not have a clock that can |
---|
991 | provide a reasonable approximation of the current time. If a 200 |
---|
992 | (OK) response to the same request would have included any of the |
---|
993 | header fields Cache-Control, Content-Location, ETag, Expires, or |
---|
994 | Vary, then those same header fields MUST be sent in a 304 response. |
---|
995 | |
---|
996 | Since the goal of a 304 response is to minimize information transfer |
---|
997 | when the recipient already has one or more cached representations, |
---|
998 | the response SHOULD NOT include representation metadata other than |
---|
999 | the above listed fields unless said metadata exists for the purpose |
---|
1000 | of guiding cache updates (e.g., future HTTP extensions). |
---|
1001 | |
---|
1002 | If the recipient of a 304 response does not have a cached |
---|
1003 | representation corresponding to the entity-tag indicated by the 304 |
---|
1004 | |
---|
1005 | |
---|
1006 | |
---|
1007 | Fielding, et al. Expires January 17, 2013 [Page 18] |
---|
1008 | |
---|
1009 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1010 | |
---|
1011 | |
---|
1012 | response, then the recipient MUST NOT use the 304 to update its own |
---|
1013 | cache. If this conditional request originated with an outbound |
---|
1014 | client, such as a user agent with its own cache sending a conditional |
---|
1015 | GET to a shared proxy, then the 304 response MAY be forwarded to that |
---|
1016 | client. Otherwise, the recipient MUST disregard the 304 response and |
---|
1017 | repeat the request without any preconditions. |
---|
1018 | |
---|
1019 | If a cache uses a received 304 response to update a cache entry, the |
---|
1020 | cache MUST update the entry to reflect any new field values given in |
---|
1021 | the response. |
---|
1022 | |
---|
1023 | 4.2. 412 Precondition Failed |
---|
1024 | |
---|
1025 | The 412 status code indicates that one or more preconditions given in |
---|
1026 | the request header fields evaluated to false when tested on the |
---|
1027 | server. This response code allows the client to place preconditions |
---|
1028 | on the current resource state (its current representations and |
---|
1029 | metadata) and thus prevent the request method from being applied if |
---|
1030 | the target resource is in an unexpected state. |
---|
1031 | |
---|
1032 | 5. Precedence |
---|
1033 | |
---|
1034 | When more than one conditional request header field is present in a |
---|
1035 | request, the order in which the fields are evaluated becomes |
---|
1036 | important. In practice, the fields defined in this document are |
---|
1037 | consistently implemented in a single, logical order, due to the fact |
---|
1038 | that entity tags are presumed to be more accurate than date |
---|
1039 | validators. For example, the only reason to send both If-Modified- |
---|
1040 | Since and If-None-Match in the same GET request is to support |
---|
1041 | intermediary caches that might not have implemented If-None-Match, so |
---|
1042 | it makes sense to ignore the If-Modified-Since when entity tags are |
---|
1043 | understood and available for the selected representation. |
---|
1044 | |
---|
1045 | The general rule of conditional precedence is that exact match |
---|
1046 | conditions are evaluated before cache-validating conditions and, |
---|
1047 | within that order, last-modified conditions are only evaluated if the |
---|
1048 | corresponding entity tag condition is not present (or not applicable |
---|
1049 | because the selected representation does not have an entity tag). |
---|
1050 | |
---|
1051 | Specifically, the fields defined by this specification are evaluated |
---|
1052 | as follows: |
---|
1053 | |
---|
1054 | 1. When If-Match is present, evaluate it: |
---|
1055 | |
---|
1056 | * if true, continue to step 3 |
---|
1057 | |
---|
1058 | * if false, respond 412 (Precondition Failed) |
---|
1059 | |
---|
1060 | |
---|
1061 | |
---|
1062 | |
---|
1063 | Fielding, et al. Expires January 17, 2013 [Page 19] |
---|
1064 | |
---|
1065 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1066 | |
---|
1067 | |
---|
1068 | 2. When If-Match is not present and If-Unmodified-Since is present, |
---|
1069 | evaluate it: |
---|
1070 | |
---|
1071 | * if true, continue to step 3 |
---|
1072 | |
---|
1073 | * if false, respond 412 (Precondition Failed) |
---|
1074 | |
---|
1075 | 3. When the method is GET and both Range and If-Range are present, |
---|
1076 | evaluate it: |
---|
1077 | |
---|
1078 | * if the validator matches, respond 206 (Partial Content) |
---|
1079 | |
---|
1080 | * if the validator does not match, respond 200 (OK) |
---|
1081 | |
---|
1082 | 4. When If-None-Match is present, evaluate it: |
---|
1083 | |
---|
1084 | * if true, all conditions are met |
---|
1085 | |
---|
1086 | * if false for GET/HEAD, respond 304 (Not Modified) |
---|
1087 | |
---|
1088 | * if false for other methods, respond 412 (Precondition Failed) |
---|
1089 | |
---|
1090 | 5. When the method is GET or HEAD, If-None-Match is not present, and |
---|
1091 | If-Modified-Since is present, evaluate it: |
---|
1092 | |
---|
1093 | * if true, all conditions are met |
---|
1094 | |
---|
1095 | * if false, respond 304 (Not Modified) |
---|
1096 | |
---|
1097 | Any extension to HTTP/1.1 that defines additional conditional request |
---|
1098 | header fields ought to define its own expectations regarding the |
---|
1099 | order for evaluating such fields in relation to those defined in this |
---|
1100 | document and other conditionals that might be found in practice. |
---|
1101 | |
---|
1102 | 6. IANA Considerations |
---|
1103 | |
---|
1104 | 6.1. Status Code Registration |
---|
1105 | |
---|
1106 | The HTTP Status Code Registry located at |
---|
1107 | <http://www.iana.org/assignments/http-status-codes> shall be updated |
---|
1108 | with the registrations below: |
---|
1109 | |
---|
1110 | |
---|
1111 | |
---|
1112 | |
---|
1113 | |
---|
1114 | |
---|
1115 | |
---|
1116 | |
---|
1117 | |
---|
1118 | |
---|
1119 | Fielding, et al. Expires January 17, 2013 [Page 20] |
---|
1120 | |
---|
1121 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1122 | |
---|
1123 | |
---|
1124 | +-------+---------------------+-------------+ |
---|
1125 | | Value | Description | Reference | |
---|
1126 | +-------+---------------------+-------------+ |
---|
1127 | | 304 | Not Modified | Section 4.1 | |
---|
1128 | | 412 | Precondition Failed | Section 4.2 | |
---|
1129 | +-------+---------------------+-------------+ |
---|
1130 | |
---|
1131 | 6.2. Header Field Registration |
---|
1132 | |
---|
1133 | The Message Header Field Registry located at <http://www.iana.org/ |
---|
1134 | assignments/message-headers/message-header-index.html> shall be |
---|
1135 | updated with the permanent registrations below (see [RFC3864]): |
---|
1136 | |
---|
1137 | +---------------------+----------+----------+-------------+ |
---|
1138 | | Header Field Name | Protocol | Status | Reference | |
---|
1139 | +---------------------+----------+----------+-------------+ |
---|
1140 | | ETag | http | standard | Section 2.3 | |
---|
1141 | | If-Match | http | standard | Section 3.1 | |
---|
1142 | | If-Modified-Since | http | standard | Section 3.3 | |
---|
1143 | | If-None-Match | http | standard | Section 3.2 | |
---|
1144 | | If-Unmodified-Since | http | standard | Section 3.4 | |
---|
1145 | | Last-Modified | http | standard | Section 2.2 | |
---|
1146 | +---------------------+----------+----------+-------------+ |
---|
1147 | |
---|
1148 | The change controller is: "IETF (iesg@ietf.org) - Internet |
---|
1149 | Engineering Task Force". |
---|
1150 | |
---|
1151 | 7. Security Considerations |
---|
1152 | |
---|
1153 | No additional security considerations have been identified beyond |
---|
1154 | those applicable to HTTP in general [Part1]. |
---|
1155 | |
---|
1156 | The validators defined by this specification are not intended to |
---|
1157 | ensure the validity of a representation, guard against malicious |
---|
1158 | changes, or detect man-in-the-middle attacks. At best, they enable |
---|
1159 | more efficient cache updates and optimistic concurrent writes when |
---|
1160 | all participants are behaving nicely. At worst, the conditions will |
---|
1161 | fail and the client will receive a response that is no more harmful |
---|
1162 | than an HTTP exchange without conditional requests. |
---|
1163 | |
---|
1164 | 8. Acknowledgments |
---|
1165 | |
---|
1166 | See Section 9 of [Part1]. |
---|
1167 | |
---|
1168 | 9. References |
---|
1169 | |
---|
1170 | |
---|
1171 | |
---|
1172 | |
---|
1173 | |
---|
1174 | |
---|
1175 | Fielding, et al. Expires January 17, 2013 [Page 21] |
---|
1176 | |
---|
1177 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1178 | |
---|
1179 | |
---|
1180 | 9.1. Normative References |
---|
1181 | |
---|
1182 | [Part1] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
---|
1183 | "HTTP/1.1, part 1: Message Routing and Syntax"", |
---|
1184 | draft-ietf-httpbis-p1-messaging-20 (work in progress), |
---|
1185 | July 2012. |
---|
1186 | |
---|
1187 | [Part2] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
---|
1188 | "HTTP/1.1, part 2: Semantics and Payloads", |
---|
1189 | draft-ietf-httpbis-p2-semantics-20 (work in progress), |
---|
1190 | July 2012. |
---|
1191 | |
---|
1192 | [Part5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
---|
1193 | "HTTP/1.1, part 5: Range Requests", |
---|
1194 | draft-ietf-httpbis-p5-range-20 (work in progress), |
---|
1195 | July 2012. |
---|
1196 | |
---|
1197 | [Part6] Fielding, R., Ed., Lafon, Y., Ed., Nottingham, M., Ed., |
---|
1198 | and J. Reschke, Ed., "HTTP/1.1, part 6: Caching", |
---|
1199 | draft-ietf-httpbis-p6-cache-20 (work in progress), |
---|
1200 | July 2012. |
---|
1201 | |
---|
1202 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |
---|
1203 | Requirement Levels", BCP 14, RFC 2119, March 1997. |
---|
1204 | |
---|
1205 | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax |
---|
1206 | Specifications: ABNF", STD 68, RFC 5234, January 2008. |
---|
1207 | |
---|
1208 | 9.2. Informative References |
---|
1209 | |
---|
1210 | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |
---|
1211 | Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |
---|
1212 | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
---|
1213 | |
---|
1214 | [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration |
---|
1215 | Procedures for Message Header Fields", BCP 90, RFC 3864, |
---|
1216 | September 2004. |
---|
1217 | |
---|
1218 | [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed |
---|
1219 | Authoring and Versioning (WebDAV)", RFC 4918, June 2007. |
---|
1220 | |
---|
1221 | Appendix A. Changes from RFC 2616 |
---|
1222 | |
---|
1223 | Allow weak entity-tags in all requests except range requests |
---|
1224 | (Sections 2.1 and 3.2). |
---|
1225 | |
---|
1226 | Change ETag header field ABNF not to use quoted-string, thus avoiding |
---|
1227 | escaping issues. (Section 2.3) |
---|
1228 | |
---|
1229 | |
---|
1230 | |
---|
1231 | Fielding, et al. Expires January 17, 2013 [Page 22] |
---|
1232 | |
---|
1233 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1234 | |
---|
1235 | |
---|
1236 | Change ABNF productions for header fields to only define the field |
---|
1237 | value. (Section 3) |
---|
1238 | |
---|
1239 | Appendix B. Imported ABNF |
---|
1240 | |
---|
1241 | The following core rules are included by reference, as defined in |
---|
1242 | Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return), |
---|
1243 | CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double |
---|
1244 | quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any |
---|
1245 | 8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII |
---|
1246 | character). |
---|
1247 | |
---|
1248 | The rules below are defined in [Part1]: |
---|
1249 | |
---|
1250 | OWS = <OWS, defined in [Part1], Section 3.2.1> |
---|
1251 | obs-text = <obs-text, defined in [Part1], Section 3.2.4> |
---|
1252 | |
---|
1253 | The rules below are defined in other parts: |
---|
1254 | |
---|
1255 | HTTP-date = <HTTP-date, defined in [Part2], Section 5.1> |
---|
1256 | |
---|
1257 | Appendix C. Collected ABNF |
---|
1258 | |
---|
1259 | ETag = entity-tag |
---|
1260 | |
---|
1261 | HTTP-date = <HTTP-date, defined in [Part2], Section 5.1> |
---|
1262 | |
---|
1263 | If-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS |
---|
1264 | entity-tag ] ) ) |
---|
1265 | If-Modified-Since = HTTP-date |
---|
1266 | If-None-Match = "*" / ( *( "," OWS ) entity-tag *( OWS "," [ OWS |
---|
1267 | entity-tag ] ) ) |
---|
1268 | If-Unmodified-Since = HTTP-date |
---|
1269 | |
---|
1270 | Last-Modified = HTTP-date |
---|
1271 | |
---|
1272 | OWS = <OWS, defined in [Part1], Section 3.2.1> |
---|
1273 | |
---|
1274 | entity-tag = [ weak ] opaque-tag |
---|
1275 | etagc = "!" / %x23-7E ; '#'-'~' |
---|
1276 | / obs-text |
---|
1277 | |
---|
1278 | obs-text = <obs-text, defined in [Part1], Section 3.2.4> |
---|
1279 | opaque-tag = DQUOTE *etagc DQUOTE |
---|
1280 | |
---|
1281 | weak = %x57.2F ; W/ |
---|
1282 | |
---|
1283 | |
---|
1284 | |
---|
1285 | |
---|
1286 | |
---|
1287 | Fielding, et al. Expires January 17, 2013 [Page 23] |
---|
1288 | |
---|
1289 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1290 | |
---|
1291 | |
---|
1292 | Appendix D. Change Log (to be removed by RFC Editor before publication) |
---|
1293 | |
---|
1294 | Changes up to the first Working Group Last Call draft are summarized |
---|
1295 | in <http://tools.ietf.org/html/ |
---|
1296 | draft-ietf-httpbis-p4-conditional-19#appendix-C>. |
---|
1297 | |
---|
1298 | D.1. Since draft-ietf-httpbis-p4-conditional-19 |
---|
1299 | |
---|
1300 | Closed issues: |
---|
1301 | |
---|
1302 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/241>: "Need to |
---|
1303 | clarify eval order/interaction of conditional headers" |
---|
1304 | |
---|
1305 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/354>: "ETags and |
---|
1306 | Conditional Requests" |
---|
1307 | |
---|
1308 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/361>: "ABNF |
---|
1309 | requirements for recipients" |
---|
1310 | |
---|
1311 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/363>: "Rare cases" |
---|
1312 | |
---|
1313 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/365>: "Conditional |
---|
1314 | Request Security Considerations" |
---|
1315 | |
---|
1316 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/371>: "If-Modified- |
---|
1317 | Since lacks definition for method != GET" |
---|
1318 | |
---|
1319 | o <http://tools.ietf.org/wg/httpbis/trac/ticket/372>: "refactor |
---|
1320 | conditional header field descriptions" |
---|
1321 | |
---|
1322 | Index |
---|
1323 | |
---|
1324 | 3 |
---|
1325 | 304 Not Modified (status code) 18 |
---|
1326 | |
---|
1327 | 4 |
---|
1328 | 412 Precondition Failed (status code) 19 |
---|
1329 | |
---|
1330 | E |
---|
1331 | ETag header field 9 |
---|
1332 | |
---|
1333 | G |
---|
1334 | Grammar |
---|
1335 | entity-tag 10 |
---|
1336 | ETag 10 |
---|
1337 | etagc 10 |
---|
1338 | If-Match 14 |
---|
1339 | If-Modified-Since 16 |
---|
1340 | |
---|
1341 | |
---|
1342 | |
---|
1343 | Fielding, et al. Expires January 17, 2013 [Page 24] |
---|
1344 | |
---|
1345 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1346 | |
---|
1347 | |
---|
1348 | If-None-Match 15 |
---|
1349 | If-Unmodified-Since 17 |
---|
1350 | Last-Modified 7 |
---|
1351 | opaque-tag 10 |
---|
1352 | weak 10 |
---|
1353 | |
---|
1354 | H |
---|
1355 | Header Fields |
---|
1356 | ETag 9 |
---|
1357 | If-Match 14 |
---|
1358 | If-Modified-Since 16 |
---|
1359 | If-None-Match 15 |
---|
1360 | If-Unmodified-Since 17 |
---|
1361 | Last-Modified 7 |
---|
1362 | |
---|
1363 | I |
---|
1364 | If-Match header field 14 |
---|
1365 | If-Modified-Since header field 16 |
---|
1366 | If-None-Match header field 15 |
---|
1367 | If-Unmodified-Since header field 17 |
---|
1368 | |
---|
1369 | L |
---|
1370 | Last-Modified header field 7 |
---|
1371 | |
---|
1372 | M |
---|
1373 | metadata 5 |
---|
1374 | |
---|
1375 | S |
---|
1376 | selected representation 4 |
---|
1377 | Status Codes |
---|
1378 | 304 Not Modified 18 |
---|
1379 | 412 Precondition Failed 19 |
---|
1380 | |
---|
1381 | V |
---|
1382 | validator 5 |
---|
1383 | strong 6 |
---|
1384 | weak 6 |
---|
1385 | |
---|
1386 | |
---|
1387 | |
---|
1388 | |
---|
1389 | |
---|
1390 | |
---|
1391 | |
---|
1392 | |
---|
1393 | |
---|
1394 | |
---|
1395 | |
---|
1396 | |
---|
1397 | |
---|
1398 | |
---|
1399 | Fielding, et al. Expires January 17, 2013 [Page 25] |
---|
1400 | |
---|
1401 | Internet-Draft HTTP/1.1, Part 4 July 2012 |
---|
1402 | |
---|
1403 | |
---|
1404 | Authors' Addresses |
---|
1405 | |
---|
1406 | Roy T. Fielding (editor) |
---|
1407 | Adobe Systems Incorporated |
---|
1408 | 345 Park Ave |
---|
1409 | San Jose, CA 95110 |
---|
1410 | USA |
---|
1411 | |
---|
1412 | EMail: fielding@gbiv.com |
---|
1413 | URI: http://roy.gbiv.com/ |
---|
1414 | |
---|
1415 | |
---|
1416 | Yves Lafon (editor) |
---|
1417 | World Wide Web Consortium |
---|
1418 | W3C / ERCIM |
---|
1419 | 2004, rte des Lucioles |
---|
1420 | Sophia-Antipolis, AM 06902 |
---|
1421 | France |
---|
1422 | |
---|
1423 | EMail: ylafon@w3.org |
---|
1424 | URI: http://www.raubacapeu.net/people/yves/ |
---|
1425 | |
---|
1426 | |
---|
1427 | Julian F. Reschke (editor) |
---|
1428 | greenbytes GmbH |
---|
1429 | Hafenweg 16 |
---|
1430 | Muenster, NW 48155 |
---|
1431 | Germany |
---|
1432 | |
---|
1433 | EMail: julian.reschke@greenbytes.de |
---|
1434 | URI: http://greenbytes.de/tech/webdav/ |
---|
1435 | |
---|
1436 | |
---|
1437 | |
---|
1438 | |
---|
1439 | |
---|
1440 | |
---|
1441 | |
---|
1442 | |
---|
1443 | |
---|
1444 | |
---|
1445 | |
---|
1446 | |
---|
1447 | |
---|
1448 | |
---|
1449 | |
---|
1450 | |
---|
1451 | |
---|
1452 | |
---|
1453 | |
---|
1454 | |
---|
1455 | Fielding, et al. Expires January 17, 2013 [Page 26] |
---|
1456 | |
---|