idnits 2.17.1 draft-reschke-http-etag-on-write-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 17. -- Found old boilerplate from RFC 3978, Section 5.5 on line 790. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 801. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 808. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 814. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC2616, but the abstract doesn't seem to directly say this. It does mention RFC2616 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (Using the creation date from RFC2616, updated by this document, for RFC5378 checks: 1997-10-16) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 22, 2006) is 6423 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) == Outdated reference: A later version (-17) exists of draft-ietf-atompub-protocol-10 -- Obsolete informational reference (is this intentional?): RFC 2518 (Obsoleted by RFC 4918) == Outdated reference: A later version (-12) exists of draft-ietf-simple-xcap-11 Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Updates: 2616 (if approved) September 22, 2006 5 Intended status: Informational 6 Expires: March 26, 2007 8 The Hypertext Transfer Protocol (HTTP) Entity Tag ("ETag") 9 Response Header in Write Operations 10 draft-reschke-http-etag-on-write-02 12 Status of this Memo 14 By submitting this Internet-Draft, each author represents that any 15 applicable patent or other IPR claims of which he or she is aware 16 have been or will be disclosed, and any of which he or she becomes 17 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on March 26, 2007. 37 Copyright Notice 39 Copyright (C) The Internet Society (2006). 41 Abstract 43 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 44 called "Entity Tag", to be returned in the "ETag" response header. 45 However, the description of this header for write operations such as 46 PUT is incomplete, and has caused confusion among developers and 47 protocol designers, and potentially interoperability problems. 49 This document explains the problem in detail and suggests both a 50 clarification for a revision to the HTTP/1.1 specification (RFC2616) 51 and a new header for use in responses, making HTTP entity tags more 52 useful for user agents that want to avoid round-trips to the server 53 after modifying a resource. 55 Editorial Note (To be removed by RFC Editor before publication) 57 Distribution of this document is unlimited. Please send comments to 58 the Hypertext Transfer Protocol (HTTP) mailing list at 59 ietf-http-wg@w3.org [1], which may be joined by sending a message 60 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 62 Discussions of the HTTP working group are archived at 63 . 65 XML versions, latest edits and the issues list for this document are 66 available from . 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 1.1. Questions out of Scope . . . . . . . . . . . . . . . . . . 4 73 1.2. The Interoperability Problem . . . . . . . . . . . . . . . 4 74 1.3. Analysis of RFC2616's Definitions . . . . . . . . . . . . 6 75 1.4. Prior Work . . . . . . . . . . . . . . . . . . . . . . . . 7 76 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 8 77 3. Clarifications on the Behavior of the 'ETag' Response 78 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 4. The 'Entity-Transform' Header . . . . . . . . . . . . . . . . 9 80 4.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9 81 5. How This Helps . . . . . . . . . . . . . . . . . . . . . . . . 10 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 83 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 85 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 86 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 87 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . . 12 88 A.1. Simple Authoring . . . . . . . . . . . . . . . . . . . . . 12 89 A.2. Setting both Content and Metadata . . . . . . . . . . . . 14 90 A.3. Setting both Content and Metadata, new style . . . . . . . 17 91 Appendix B. Change Log (to be removed by RFC Editor before 92 publication) . . . . . . . . . . . . . . . . . . . . 18 93 B.1. Since draft-reschke-http-etag-on-write-00 . . . . . . . . 18 94 B.2. Since draft-reschke-http-etag-on-write-01 . . . . . . . . 18 95 Appendix C. Open issues (to be removed by RFC Editor prior to 96 publication) . . . . . . . . . . . . . . . . . . . . 18 97 C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18 99 Intellectual Property and Copyright Statements . . . . . . . . . . 20 101 1. Introduction 103 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 104 called "Entity Tag", to be returned in the "ETag" response header 105 (see [RFC2616], Section 14.19). However, the description of this 106 header for write operations such as PUT is incomplete, and has caused 107 confusion among developers and protocol designers, and potentially 108 interoperability problems. 110 This document explains the problem in detail and suggests both a 111 clarification for a revision to [RFC2616] and a new header for use in 112 responses, making HTTP entity tags more useful for user agents that 113 want to avoid round-trips to the server after modifying a resource. 115 1.1. Questions out of Scope 117 Note that there is a related problem: modifying content-negotiated 118 resources. Here the consensus seems to be simply not to do it. 119 Instead, the origin server should reveal specific URIs of content 120 that is not content-negotiated in the Content-Location response 121 header ([RFC2616], Section 14.14), and user agents should use this 122 more specific URI for authoring. Thus, the remainder of this 123 document will focus on resources for which no content negotiation 124 takes place. 126 Another related question is the usability of the weak entity tags for 127 authoring (see [RFC2616], Section 13.3.3). Although this document 128 focuses on the usage of strong entity tags, it is believed that the 129 changes suggested in this document could be applied to weak entity 130 tags as well. 132 1.2. The Interoperability Problem 134 For a long time, nobody realized that there was a problem at all, or 135 those who realized preferred to ignore it. 137 Server implementers added code that would return the new value of the 138 "ETag" header in a response to a successful PUT request. After all, 139 the client could be interested in it. 141 User agent developers in turn were happy to get a new "ETag" value, 142 saving a subsequent HEAD request to retrieve the new entity tag. 144 However, at some point of time, potentially during a Web Distributed 145 Authoring and Versioning (WebDAV, [RFC2518]) interoperability event, 146 client programmers asked server programmers to always return "ETag" 147 headers upon PUT, never ever to change the entity tag without "good 148 reason", and - by the way - always to guarantee that the server 149 stores the new content octet-by-octet. 151 From the perspective of client software that wants to treat an HTTP 152 server as a file system replacement, this makes a lot of sense. 153 After all, when one writes to a file one usually expects the file 154 system to store what was written, and not to unexpectedly change the 155 contents. 157 However, in general, an HTTP server is not a file system replacement. 158 There may be some that have been designed that way, and some that 159 expose some parts of their namespace that have this quality. But in 160 general, HTTP server implementers have a lot of freedom in how 161 resources are implemented. Indeed, this flexibility is one of the 162 reasons for HTTP's success, allowing it to be used for a wide range 163 of tasks, of which replacing file systems is just one (and not 164 necessarily the most interesting one). 166 In particular: 168 o A server may not store a resource as a binary object - in this 169 case, the representation returned in a subsequent GET request may 170 just be similar, but not identical to what was written. Good 171 examples are servers that use HTTP to access XML data ([XCAP]), 172 Calendaring data ([CALDAV]) or newsfeed data ([APP]). 174 o A server may change the data being written on purpose, while it's 175 being written. Examples that immediately come to mind are keyword 176 substitution in a source control system, or filters that remove 177 potentially insecure parts out of HTML pages. 179 Furthermore: 181 o An "unrelated" method such as WebDAV's PROPPATCH (see [RFC2518], 182 Section 8.2) may affect the entity body and therefore the entity 183 tag in an unexpected way, because the server stores some or all of 184 the WebDAV properties inside the entity body (for instance, GPS 185 information inside a JPG image file). 187 As long as servers store the content octet-by-octet, and return 188 exactly what the client wrote, there is no problem at all. 190 Things get more interesting when a server does change the content, 191 such as in the "simple authoring" example given in Appendix A.1. 192 Here, the server does change the content upon writing to the 193 resource, yet no harm is done, because the final state of the 194 resource on the server does not depend on the client being aware of 195 that. 197 All of the content rewriting examples mentioned above have this 198 quality: the client can safely continue to edit the entity it sent, 199 because the result of the transformation done by the server will be 200 the same in the end. Formally, if we call the server-side 201 transformation "t", the initial content "c", and the client-side 202 editing steps "e1" and "e2", then 204 t(e2(e1(c))) = t(e2(t(e1(c)))) 206 e.g., it's irrelevant whether the client obtained the current entity 207 body before doing its second edit. 209 [[example.for.non.safe.rewrite: Question: does anybody know a real- 210 world example for server-side content rewriting where the above is 211 not true? --julian.reschke@greenbytes.de]] 213 Problems will only occur if the client uses the entity body it sent, 214 and the entity tag it obtained in return, in subsequent requests that 215 only transfer part of the entity body, such as GET or PUT requests 216 using the "Range" request header (see [RFC2616], Section 14.35). 218 Furthermore, some clients need to expose the actual contents to the 219 end user. These clients will have to ensure that they really have 220 the current representation. 222 Entity bodies (and thus entity tags) changing due to side effects of 223 seemingly unrelated requests are indeed a problem, as demonstrated in 224 Appendix A.2, and this specification proposes a way to resolve this 225 in Section 3. 227 1.3. Analysis of RFC2616's Definitions 229 There are several places in the HTTP/1.1 specification ([RFC2616]) 230 mentioning the "ETag" response header. 232 Let us start with the header definition in Section 14.19: 234 The ETag response-header field provides the current value of the 235 entity tag for the requested variant. Sections 14.24, 14.26 and 236 14.44 describe the headers used with entity tags. The entity tag 237 MAY be used for comparison with other entities from the same 238 resource (see Section 13.3.3). 240 The meaning of a "response-header" in turn is defined in Section 6.2: 242 The response-header fields allow the server to pass additional 243 information about the response which cannot be placed in the 244 Status-Line. These header fields give information about the 245 server and about further access to the resource identified by the 246 Request-URI. 248 The "ETag" response header itself is mentioned mainly in the context 249 of cache validation, such as in Section 13.3.2. What is missing is a 250 coherent description on how the origin server can notify the user- 251 agent when the entity tag changes as result of a write operation, 252 such as PUT. 254 Indeed, the definition of the 201 Created status code mentions entity 255 tags (Section 10.2.2): 257 A 201 response MAY contain an ETag response header field 258 indicating the current value of the entity tag for the requested 259 variant just created, see Section 14.19. 261 The "ETag" response header is mentioned again in the definition of 262 206 Partial Content (Section 10.2.7) and 304 Not Modified (Section 263 10.3.5), but notably missing are statements about other 2xx series 264 status codes that can occur upon a successful PUT operation, such as 265 200 OK (Section 10.2.1) and 204 No Content (Section 10.2.5). 267 Summarizing, the specification is a bit vague about what an ETag 268 response header upon a write operation means, but this problem is 269 somewhat mitigated by the precise definition of a response header. A 270 proposal for enhancing [RFC2616] in this regard is made in Section 3 271 below. 273 1.4. Prior Work 275 While working on the revision of [RFC2518], the IETF WebDAV working 276 group realized that this is a generic problem that needs attention 277 independently of WebDAV. An initial attempt was made with 278 [draft-whitehead-http-etag] in February 2006, but no progress was 279 made since. 281 At the time of this writing in August 2006, two specifications based 282 on HTTP were under IESG review, taking two opposite approaches: 284 o Section 8.5 of [XCAP] makes it a MUST-level requirement to return 285 an entity tag upon PUT, even though the very nature of an XCAP 286 server will cause it to rewrite contents (due to its XML-based 287 storage). 289 o Section 5.3.4 of [CALDAV] explicitly forbids ("MUST NOT") 290 returning an entity tag upon PUT if the content was rewritten. 292 In essence, this makes it impossible to implement an HTTP resource 293 that conforms to both specifications. Due to the differing use cases 294 of XCAP and CalDAV, this may not be a problem in practice, but the 295 disagreement in itself is scary. Publication of these specifications 296 on the standards track will make it much harder for future protocols 297 to deal with this topic in a meaningful way (comments were sent 298 during IETF Last Call for CalDAV, see 299 ). 301 2. Notational Conventions 303 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 304 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 305 document are to be interpreted as described in [RFC2119]. 307 The terminology used here follows and extends that in the HTTP 308 specification [RFC2616], notably the augmented Backus-Naur Form (BNF) 309 defined in Section 2.1 of that document. 311 3. Clarifications on the Behavior of the 'ETag' Response Header 313 This section describes a minimal change to [RFC2616], proposed in . 316 At the end of Section 10.2 of [RFC2616], add: 318 The response MAY contain an ETag response header field indicating 319 the current value of the entity tag (Section 14.19) for the 320 requested variant. The value SHOULD be the same as the one 321 returned upon a subsequent HEAD request addressing the same 322 variant. 324 In Section 10.2.1 of [RFC2616], remove: 326 A 201 response MAY contain an ETag response header field 327 indicating the current value of the entity tag for the requested 328 variant just created, see Section 14.19. 330 In essence, this moves the statement about entity tags in write 331 operations from the specific case of status 201 Created into the more 332 generic description of the 2xx series status codes. 334 [[rcf2616.enhancements: Should "requested variant" be clarified in 335 the context of write operations? --julian.reschke@greenbytes.de]] 337 4. The 'Entity-Transform' Header 339 The 'Entity-Transform' entity header provides information about 340 whether a transformation has been applied to an entity body. 342 When used in an HTTP request, its meaning is undefined. In an HTTP 343 response, it provides information whether the server has applied a 344 transformation when the entity was stored last. 346 In general, entity headers may be stored in intermediates. The main 347 use of this header however applies to the HTTP PUT method, of which 348 by default the results are not cacheable (see [RFC2616], Section 349 9.6). In addition, the value format is defined so that a client can 350 reliably detect whether the information is fresh. 352 Format: 354 Entity-Transform = "Entity-Transform" ":" entity-transform-spec 355 entity-transform-spec = entity-transform-keyword SP entity-tag 356 entity-transform-keyword = "identity" | "unspecified" 357 ; entity-tag: defined in [RFC2616], Section 3.11 359 The entity-tag specifies the entity body to which this information 360 applies. 362 An entity-transform-keyword of "identity" specifies that the origin 363 server has stored the entity octet-by-octet, thus the user agent MAY 364 use a local copy of the entity body with the given entity-tag for 365 subsequent requests that rely on octet-by-octet identity (such as a 366 PUT with "Range" request header). 368 Both the absence of this response header and any entity-transform- 369 keyword value other than "identity" specify that the origin server 370 may have transformed the entity before storage, thus a subsequent 371 retrieval will not necessarily return an exact copy of the submitted 372 entity. 374 4.1. Examples 376 Content was stored octet-by-octet: 378 HTTP/1.1 200 OK 379 ETag: "1" 380 Entity-Transform: identity "1" 381 Content was transformed: 383 HTTP/1.1 200 OK 384 ETag: "2" 385 Entity-Transform: unspecified "2" 387 Response containing a stale "Entity-Transform" header: 389 HTTP/1.1 200 OK 390 ETag: "3" 391 Entity-Transform: unspecified "2" 393 Note that in this case the newly assigned entity tag and the entity 394 tag returned in "Entity-Transform" do not match, thus the client is 395 aware that the header value is stale and can't be used. 397 5. How This Helps 399 The clarification of [RFC2616] (see Section 3) makes it clear that 400 user agents can use "ETag" headers obtained in write operations, as 401 long as they do not require octet-by-octet identity. In particular, 402 a new entity tag can be returned for any method, such as a WebDAV 403 PROPPATCH (see [RFC2518], Section 8.2. This helps dealing with the 404 problem described in Appendix A.2. See Appendix A.3 for details. 406 The addition of the "Entity-Transform" header (see Section 4) enables 407 origin servers to signal that they stored an exact copy of the 408 content, thus allowing clients not to refetch the content. Note that 409 by default (in absence of the response header), a client can not make 410 any assumptions about the server's behavior in this regard. Thus 411 clients will only benefit from new servers explicitly setting the new 412 header. 414 6. IANA Considerations 416 This document specifies the new HTTP header listed below. 418 Header field name: Entity-Transform 420 Applicable protocol: http 422 Status: informational 423 Author/Change controller: IETF 425 Specification document: Section 4 of this specification 427 7. Security Considerations 429 This specification introduces no new security considerations beyond 430 those discussed in Section 15 of [RFC2616]. 432 8. References 434 8.1. Normative References 436 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 437 Requirement Levels", BCP 14, RFC 2119, March 1997. 439 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 440 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 441 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 443 8.2. Informative References 445 [APP] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 446 Publishing Protocol", draft-ietf-atompub-protocol-10 (work 447 in progress), September 2006. 449 [CALDAV] Daboo, C., Desruisseaux, B., and L. Dusseault, 450 "Calendaring Extensions to WebDAV (CalDAV)", 451 draft-dusseault-caldav-15 (work in progress), 452 September 2006. 454 [HTML] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 455 Specification", W3C REC-html401-19991224, December 1999, 456 . 458 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 459 Jensen, "HTTP Extensions for Distributed Authoring -- 460 WEBDAV", RFC 2518, February 1999. 462 [XCAP] Rosenberg, J., "The Extensible Markup Language (XML) 463 Configuration Access Protocol (XCAP)", 464 draft-ietf-simple-xcap-11 (work in progress), May 2006. 466 [draft-whitehead-http-etag] 467 Whitehead, J., "Design Considerations for State 468 Identifiers in HTTP and WebDAV", 469 draft-whitehead-http-etag-00 (work in progress), 470 February 2006. 472 URIs 474 [1] 476 [2] 478 Appendix A. Use Cases 480 A.1. Simple Authoring 482 Let us consider a server not having the quality of preserving octet- 483 by-octet identity, for instance because of SVN-style keyword 484 expansion in text content (). 487 In this case, the client has previously retrieved the representation 488 for , and the server has returned the ETag 489 "1": 491 >> Request (1) 493 GET /test HTTP/1.1 494 Host: example.com 496 >> Response (1) 498 HTTP/1.1 200 OK 499 Content-Type: text/plain 500 ETag: "1" 502 # $Revision: 1 $ 503 Sample text. 505 The client now wants to update the resource. To avoid overwriting 506 somebody else's changes, it submits the PUT request with the HTTP 507 "If-Match" request header (see [RFC2616], Section 14.24): 509 >> Request (2) 511 PUT /test HTTP/1.1 512 Host: example.com 513 If-Match: "1" 515 # $Revision: 1 $ 516 New sample text. 518 If the resource was modified in the meantime, the server will reject 519 the request with a 412 Precondition Failed status: 521 >> Response (2a) 523 HTTP/1.1 412 Precondition Failed 524 Content-Type: text/plain 526 Precondition Failed: entity tag supplied in If-Match request header 527 did not match current. 529 In this case, the client usually has take care of merging the changes 530 made locally with those made on the server ("Merge Conflict"). 532 If there was no overlapping update, the server will execute the 533 request and return a new entity tag: 535 >> Response (2b) 537 HTTP/1.1 200 OK 538 Content-Type: text/plain 539 ETag: "2" 541 Note however, that at this point the client knows the new entity tag, 542 but doesn not know the current representation, which will have been 543 updated by the server to: 545 # $Revision: 2 $ 546 New sample text. 548 What seems to be a problem at first may not be a real problem in 549 practice. Let us assume that the client continues editing the 550 resource, using the entity tag obtained from the previous request, 551 but editing the entity it last sent: 553 >> Request (3) 555 PUT /test HTTP/1.1 556 Host: example.com 557 If-Match: "2" 559 # $Revision: 1 $ 560 A third attempt. 562 Assuming there was no overlapping update, the PUT request will 563 succeed: 565 >> Response (3) 567 HTTP/1.1 200 OK 568 Content-Type: text/plain 569 ETag: "3" 571 Note that the only problem here is that the client doesn't have an 572 exact copy of the entity it's editing. However, from the server's 573 point of view this is entirely irrelevant, because the "Revision" 574 keyword will be automatically updated upon every write anyway. 576 In any case, the final contents will be: 578 # $Revision: 3 $ 579 A third attempt. 581 A.2. Setting both Content and Metadata 583 In this example, the server exposes data extracted from the HTML 584 element ([HTML], Section 7.4.2) as a custom WebDAV property 585 ([RFC2518], Section 4), allowing both read and write access. 587 In the first step, the client obtains the current representation for 588 <http://example.com/test.html>: 590 >> Request (1) 592 GET /test.html HTTP/1.1 593 Host: example.com 594 >> Response (1) 596 HTTP/1.1 200 OK 597 Content-Type: text/html 598 ETag: "A" 600 <html> 601 <head> 602 </head> 603 <body> 604 </body> 605 </html> 607 Next, it adds one paragraph to the <body> element, and gets back a 608 new entity tag: 610 >> Request (2) 612 PUT /test.html HTTP/1.1 613 Host: example.com 614 If-Match: "A" 616 <html> 617 <head> 618 </head> 619 <body> 620 <p>First paragraph.</p> 621 </body> 622 </html> 624 >> Response (2) 626 HTTP/1.1 200 OK 627 ETag: "B" 629 Next, the client sets a custom "title" property (see [RFC2518], 630 Section 8.2): 632 >> Request (3) 634 PROPPATCH /test.html HTTP/1.1 635 Host: example.com 636 Content-Type: application/xml 638 <proppatch xmlns="DAV:"> 639 <set> 640 <prop> 641 <title xmlns="http://ns.example.org/"> 642 A sample document 643 644 645 646 648 >> Response (3) 650 HTTP/1.1 207 Multi-Status 651 Content-Type: application/xml 653 654 655 /test.html 656 657 658 659 </prop> 660 <status>HTTP/1.1 2OO OK</status> 661 </propstat> 662 </response> 663 </multistatus> 665 The server knows how to propagate property changes into the HTML 666 content, so it updates the entity by adding an HTML title document 667 accordingly. This causes the entity tag changing to "C". 669 The new entity body is shown below, but the client does not realize 670 that it did change at all. 672 <html> 673 <head> 674 <title>A sample document 675 676 677

First paragraph.

678 679 680 A subsequent attempt by the client to update the entity body will 681 fail, unless it realizes that changing WebDAV properties may affect 682 the entity as well. In this case, it would have had to get the 683 current entity tag before proceeding. Of course, this introduces an 684 additional round-trip, and a timing window during which overlapping 685 updates by other clients would go unnoticed. 687 A.3. Setting both Content and Metadata, new style 689 Below we repeat the example from above (Appendix A.2), but here the 690 origin server returns entity tags for all write operations, and the 691 user agent knows how to deal with them. That is, both take advantage 692 of [RFC2616] already allows. 694 >> Request (3) 696 PROPPATCH /test.html HTTP/1.1 697 Host: example.com 698 Content-Type: application/xml 700 701 702 703 704 A sample document 705 706 707 708 710 >> Response (3) 712 HTTP/1.1 207 Multi-Status 713 Content-Type: application/xml 714 ETag: "C" 716 717 718 /test.html 719 720 721 722 </prop> 723 <status>HTTP/1.1 2OO OK</status> 724 </propstat> 725 </response> 726 </multistatus> 727 As before, this causes the entity to change, and a new entity tag to 728 be assigned. But in this case, the origin server actually notifies 729 the client of the changed state by including the "ETag" response 730 header. 732 The client now will be aware that the requested entity change, and 733 can use the new entity tag in subsequent requests (potentially after 734 refreshing the local copy). 736 Appendix B. Change Log (to be removed by RFC Editor before publication) 738 B.1. Since draft-reschke-http-etag-on-write-00 740 Add and resolves issues "entity-header" and "extensibility", by 741 removing the extension hooks, and by redefining the header to it can 742 be used as an Entity header. 744 B.2. Since draft-reschke-http-etag-on-write-01 746 Update APP and CALDAV references. Remove RFC3986 reference (not 747 needed anymore after the simplication in draft 01). Fix typo in 748 header description ("submitted entity", not "stored entity"). Remove 749 comparison about how XCAP and CALDAV profile RFC2616: after all, both 750 mandate a behaviour that was legal but optional before. Add 751 "Updates: RFC2616". 753 Appendix C. Open issues (to be removed by RFC Editor prior to 754 publication) 756 C.1. edit 758 Type: edit 760 julian.reschke@greenbytes.de (2006-08-10): Umbrella issue for 761 editorial fixes/enhancements. 763 Author's Address 765 Julian F. Reschke 766 greenbytes GmbH 767 Hafenweg 16 768 Muenster, NW 48155 769 Germany 771 Phone: +49 251 2807760 772 Fax: +49 251 2807761 773 Email: julian.reschke@greenbytes.de 774 URI: http://greenbytes.de/tech/webdav/ 776 Full Copyright Statement 778 Copyright (C) The Internet Society (2006). 780 This document is subject to the rights, licenses and restrictions 781 contained in BCP 78, and except as set forth therein, the authors 782 retain all their rights. 784 This document and the information contained herein are provided on an 785 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 786 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 787 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 788 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 789 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 790 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 792 Intellectual Property 794 The IETF takes no position regarding the validity or scope of any 795 Intellectual Property Rights or other rights that might be claimed to 796 pertain to the implementation or use of the technology described in 797 this document or the extent to which any license under such rights 798 might or might not be available; nor does it represent that it has 799 made any independent effort to identify any such rights. Information 800 on the procedures with respect to rights in RFC documents can be 801 found in BCP 78 and BCP 79. 803 Copies of IPR disclosures made to the IETF Secretariat and any 804 assurances of licenses to be made available, or the result of an 805 attempt made to obtain a general license or permission for the use of 806 such proprietary rights by implementers or users of this 807 specification can be obtained from the IETF on-line IPR repository at 808 http://www.ietf.org/ipr. 810 The IETF invites any interested party to bring to its attention any 811 copyrights, patents or patent applications, or other proprietary 812 rights that may cover technology that may be required to implement 813 this standard. Please address the information to the IETF at 814 ietf-ipr@ietf.org. 816 Acknowledgment 818 Funding for the RFC Editor function is provided by the IETF 819 Administrative Support Activity (IASA).