idnits 2.17.1 draft-reschke-http-etag-on-write-08.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, updated by RFC 4748 on line 877. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 888. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 895. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 901. 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 IETF Trust 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 (October 25, 2007) is 6000 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: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2518 (Obsoleted by RFC 4918) Summary: 3 errors (**), 0 flaws (~~), 2 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) October 25, 2007 5 Intended status: Experimental 6 Expires: April 27, 2008 8 The Hypertext Transfer Protocol (HTTP) Entity Tag ("ETag") 9 Response Header in Write Operations 10 draft-reschke-http-etag-on-write-08 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 April 27, 2008. 37 Copyright Notice 39 Copyright (C) The IETF Trust (2007). 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 67 . 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 . . . . . . . . . . . . . . . . . . . . . . . . . 10 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. Simple Authoring, with Entity-Transform header . . . . . . 14 90 A.3. Setting both Content and Metadata . . . . . . . . . . . . 15 91 A.4. Setting both Content and Metadata, new style . . . . . . . 17 92 Appendix B. Change Log (to be removed by RFC Editor before 93 publication) . . . . . . . . . . . . . . . . . . . . 18 94 B.1. Since draft-reschke-http-etag-on-write-00 . . . . . . . . 18 95 B.2. Since draft-reschke-http-etag-on-write-01 . . . . . . . . 18 96 B.3. Since draft-reschke-http-etag-on-write-02 . . . . . . . . 19 97 B.4. Since draft-reschke-http-etag-on-write-03 . . . . . . . . 19 98 B.5. Since draft-reschke-http-etag-on-write-04 . . . . . . . . 19 99 B.6. Since draft-reschke-http-etag-on-write-05 . . . . . . . . 19 100 B.7. Since draft-reschke-http-etag-on-write-06 . . . . . . . . 19 101 B.8. Since draft-reschke-http-etag-on-write-07 . . . . . . . . 19 102 Appendix C. Open issues (to be removed by RFC Editor prior to 103 publication) . . . . . . . . . . . . . . . . . . . . 19 104 C.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 106 Intellectual Property and Copyright Statements . . . . . . . . . . 21 108 1. Introduction 110 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 111 called "Entity Tag", to be returned in the "ETag" response header 112 (see [RFC2616], Section 14.19). However, the description of this 113 header for write operations such as PUT is incomplete, and has caused 114 confusion among developers and protocol designers, and potentially 115 interoperability problems. 117 This document explains the problem in detail and suggests both a 118 clarification for a revision to [RFC2616] and a new header for use in 119 responses, making HTTP entity tags more useful for user agents that 120 want to avoid round-trips to the server after modifying a resource. 122 1.1. Questions out of Scope 124 Note that there is a related problem: modifying content-negotiated 125 resources. Here the consensus seems to be simply not to do it. 126 Instead, the origin server should reveal specific URIs of content 127 that is not content-negotiated in the Content-Location response 128 header ([RFC2616], Section 14.14), and user agents should use this 129 more specific URI for authoring. Thus, the remainder of this 130 document will focus on resources for which no content negotiation 131 takes place. 133 Another related question is the usability of the weak entity tags for 134 authoring (see [RFC2616], Section 13.3.3). Although this document 135 focuses on the usage of strong entity tags, it is believed that the 136 changes suggested in this document could be applied to weak entity 137 tags as well. 139 1.2. The Interoperability Problem 141 For a long time, nobody realized that there was a problem at all, or 142 those who realized preferred to ignore it. 144 Server implementers added code that would return the new value of the 145 "ETag" header in a response to a successful PUT request. After all, 146 the client could be interested in it. 148 User agent developers in turn were happy to get a new "ETag" value, 149 saving a subsequent HEAD request to retrieve the new entity tag. 151 However, at some point of time, potentially during a Web Distributed 152 Authoring and Versioning (WebDAV, [RFC2518], obsoleted by [RFC4918]) 153 interoperability event, client programmers asked server programmers 154 to always return "ETag" headers upon PUT, never ever to change the 155 entity tag without "good reason", and - by the way - always to 156 guarantee that the server stores the new content octet-by-octet. 158 From the perspective of client software that wants to treat an HTTP 159 server as a file system replacement, this makes a lot of sense. 160 After all, when one writes to a file one usually expects the file 161 system to store what was written, and not to unexpectedly change the 162 contents. 164 However, in general, an HTTP server is not a file system replacement. 165 There may be some that have been designed that way, and some that 166 expose some parts of their namespace that have this quality. But in 167 general, HTTP server implementers have a lot of freedom in how 168 resources are implemented. Indeed, this flexibility is one of the 169 reasons for HTTP's success, allowing it to be used for a wide range 170 of tasks, of which replacing file systems is just one (and not 171 necessarily the most interesting one). 173 In particular: 175 o A server may not store a resource as a binary object - in this 176 case, the representation returned in a subsequent GET request may 177 just be similar, but not identical to what was written. Good 178 examples are servers that use HTTP to access XML data ([RFC4825]), 179 Calendaring data ([RFC4791]) or newsfeed data ([RFC5023]). 181 o A server may change the data being written on purpose, while it is 182 being written. Examples that immediately come to mind are keyword 183 substitution in a source control system, or filters that remove 184 potentially insecure parts out of HTML pages. 186 Furthermore: 188 o An "unrelated" method such as WebDAV's PROPPATCH (see [RFC4918], 189 Section 9.2) may affect the entity body and therefore the entity 190 tag in an unexpected way, because the server stores some or all of 191 the WebDAV properties inside the entity body (for instance, GPS 192 information inside a JPG image file). 194 As long as servers store the content octet-by-octet, and return 195 exactly what the client wrote, there is no problem at all. 197 Things get more interesting when a server does change the content, 198 such as in the "simple authoring" example given in Appendix A.1. 199 Here, the server does change the content upon writing to the 200 resource, yet no harm is done, because the final state of the 201 resource on the server does not depend on the client being aware of 202 that. 204 All of the content rewriting examples mentioned above have this 205 quality: the client can safely continue to edit the entity it sent, 206 because the result of the transformation done by the server will be 207 the same in the end. Formally, if we call the server-side 208 transformation "t", the initial content "c", and the client-side 209 editing steps "e1" and "e2", then 211 t(e2(e1(c))) = t(e2(t(e1(c)))) 213 e.g., it is irrelevant whether the client obtained the current entity 214 body before doing its second edit. 216 [[example.for.non.safe.rewrite: Question: does anybody know a real- 217 world example for server-side content rewriting where the above is 218 not true? --julian.reschke@greenbytes.de]] 220 Problems will only occur if the client uses the entity body it sent, 221 and the entity tag it obtained in return, in subsequent requests that 222 only transfer part of the entity body, such as GET or PUT requests 223 using the "Range" request header (see [RFC2616], Section 14.35). 225 Furthermore, some clients need to expose the actual contents to the 226 end user. These clients will have to ensure that they really have 227 the current representation. 229 Entity bodies (and thus entity tags) changing due to side effects of 230 seemingly unrelated requests are indeed a problem, as demonstrated in 231 Appendix A.3, and this specification proposes a way to resolve this 232 in Section 3. 234 1.3. Analysis of RFC2616's Definitions 236 There are several places in the HTTP/1.1 specification ([RFC2616]) 237 mentioning the "ETag" response header. 239 Let us start with the header definition in Section 14.19: 241 The ETag response-header field provides the current value of the 242 entity tag for the requested variant. Sections 14.24, 14.26 and 243 14.44 describe the headers used with entity tags. The entity tag 244 MAY be used for comparison with other entities from the same 245 resource (see Section 13.3.3). 247 The meaning of a "response-header" in turn is defined in Section 6.2: 249 The response-header fields allow the server to pass additional 250 information about the response which cannot be placed in the 251 Status-Line. These header fields give information about the 252 server and about further access to the resource identified by the 253 Request-URI. 255 The "ETag" response header itself is mentioned mainly in the context 256 of cache validation, such as in Section 13.3.2. What is missing is a 257 coherent description on how the origin server can notify the user- 258 agent when the entity tag changes as result of a write operation, 259 such as PUT. 261 Indeed, the definition of the 201 Created status code mentions entity 262 tags (Section 10.2.2): 264 A 201 response MAY contain an ETag response header field 265 indicating the current value of the entity tag for the requested 266 variant just created, see Section 14.19. 268 The "ETag" response header is mentioned again in the definition of 269 206 Partial Content (Section 10.2.7) and 304 Not Modified (Section 270 10.3.5), but notably missing are statements about other 2xx series 271 status codes that can occur upon a successful PUT operation, such as 272 200 OK (Section 10.2.1) and 204 No Content (Section 10.2.5). 274 Summarizing, the specification is a bit vague about what an ETag 275 response header upon a write operation means, but this problem is 276 somewhat mitigated by the precise definition of a response header. A 277 proposal for enhancing [RFC2616] in this regard is made in Section 3 278 below. 280 1.4. Prior Work 282 While working on the revision of [RFC2518], the IETF WebDAV working 283 group realized that this is a generic problem that needs attention 284 independently of WebDAV. An initial attempt was made with 285 [draft-whitehead-http-etag] in February 2006, but no progress was 286 made since. 288 At the time of this writing in May 2007, two specifications based on 289 HTTP were just published by the RFC Editor, taking two opposite 290 approaches: 292 o Section 8.5 of [RFC4825] makes it a MUST-level requirement to 293 return an entity tag upon PUT, even though the very nature of an 294 XCAP server will cause it to rewrite contents (due to its XML- 295 based storage). 297 o Section 5.3.4 of [RFC4791] explicitly forbids ("MUST NOT") 298 returning an entity tag upon PUT if the content was rewritten. 300 In essence, this makes it impossible to implement an HTTP resource 301 that conforms to both specifications. Due to the differing use cases 302 of XCAP and CalDAV, this may not be a problem in practice, but the 303 disagreement in itself is scary. Publication of these specifications 304 on the standards track will make it much harder for future protocols 305 to deal with this topic in a meaningful way (comments were sent 306 during IETF Last Call for CalDAV, see 307 ). 309 2. Notational Conventions 311 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 312 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 313 document are to be interpreted as described in [RFC2119]. 315 The terminology used here follows and extends that in the HTTP 316 specification [RFC2616], notably the augmented Backus-Naur Form (BNF) 317 defined in Section 2.1 of that document. 319 3. Clarifications on the Behavior of the 'ETag' Response Header 321 This section describes a minimal change to [RFC2616], proposed in . 324 At the end of Section 10.2 of [RFC2616], add: 326 The response MAY contain an ETag response header field indicating 327 the current value of the entity tag (Section 14.19) for the 328 requested variant. The value SHOULD be the same as the one 329 returned upon a subsequent HEAD request addressing the same 330 variant. 332 In Section 10.2.1 of [RFC2616], remove: 334 A 201 response MAY contain an ETag response header field 335 indicating the current value of the entity tag for the requested 336 variant just created, see Section 14.19. 338 In essence, this moves the statement about entity tags in write 339 operations from the specific case of status 201 Created into the more 340 generic description of the 2xx series status codes. 342 Note that the term "requested variant" is somewhat misleading, in 343 particular in the context of write operations (see 344 on the 345 RFC2616bis issues list). 347 4. The 'Entity-Transform' Header 349 The 'Entity-Transform' entity header provides information about 350 whether a transformation has been applied to an entity body. 352 When used in an HTTP request, its meaning is undefined. In an HTTP 353 response, it provides information whether the server has applied a 354 transformation when the entity was stored last. 356 In general, entity headers may be stored in intermediates. The main 357 use of this header however applies to the HTTP PUT method, of which 358 by default the results are not cacheable (see [RFC2616], Section 359 9.6). In addition, the value format is defined so that a client can 360 reliably detect whether the information is fresh. 362 Format: 364 Entity-Transform = "Entity-Transform" ":" entity-transform-spec 365 entity-transform-spec = entity-transform-keyword SP entity-tag 366 entity-transform-keyword = "identity" | "unspecified"| token 368 entity-tag = 369 token = 371 The entity-tag specifies the entity body to which this information 372 applies. 374 An entity-transform-keyword of "identity" specifies that the origin 375 server has stored the entity octet-by-octet, thus the user agent MAY 376 use a local copy of the entity body with the given entity-tag for 377 subsequent requests that rely on octet-by-octet identity (such as a 378 PUT with "Range" request header). 380 Both the absence of this response header and any entity-transform- 381 keyword value other than "identity" specify that the origin server 382 may have transformed the entity before storage, thus a subsequent 383 retrieval will not necessarily return an exact copy of the submitted 384 entity. 386 Note: usage of keywords other than "identity" or "unspecified" is 387 reserved for future revisisions of this specification. 389 Further note that the definition of the "identity" keyword is 390 independant of the type of entity-tag. Thus, when "identity" is 391 returned with a weak entity-tag, the client can indeed rely on 392 octet-by-octet identity. 394 4.1. Examples 396 Content was stored octet-by-octet: 398 HTTP/1.1 200 OK 399 ETag: "1" 400 Entity-Transform: identity "1" 402 Content was transformed: 404 HTTP/1.1 200 OK 405 ETag: "2" 406 Entity-Transform: unspecified "2" 408 Response containing a stale "Entity-Transform" header: 410 HTTP/1.1 200 OK 411 ETag: "3" 412 Entity-Transform: unspecified "2" 414 Note that in this case the newly assigned entity tag and the entity 415 tag returned in "Entity-Transform" do not match, thus the client is 416 aware that the header value is stale and can't be used. 418 5. How This Helps 420 The clarification of [RFC2616] (see Section 3) makes it clear that 421 user agents can use "ETag" headers obtained in write operations, as 422 long as they do not require octet-by-octet identity. In particular, 423 a new entity tag can be returned for any method, such as a WebDAV 424 PROPPATCH (see [RFC4918], Section 9.2). This helps dealing with the 425 problem described in Appendix A.3. See Appendix A.4 for details. 427 The addition of the "Entity-Transform" header (see Section 4) enables 428 origin servers to signal that they stored an exact copy of the 429 content, thus allowing clients not to refetch the content. Note that 430 by default (in absence of the response header), a client can not make 431 any assumptions about the server's behavior in this regard. Thus 432 clients will only benefit from new servers explicitly setting the new 433 header. 435 6. IANA Considerations 437 This document specifies the new HTTP header listed below. 439 Header field name: Entity-Transform 441 Applicable protocol: http 443 Status: informational 445 Author/Change controller: IETF 447 Specification document: Section 4 of this specification 449 7. Security Considerations 451 This specification introduces no new security considerations beyond 452 those discussed in Section 15 of [RFC2616]. 454 8. References 456 8.1. Normative References 458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 459 Requirement Levels", BCP 14, RFC 2119, March 1997. 461 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 462 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 463 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 465 8.2. Informative References 467 [HTML] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 468 Specification", W3C REC-html401-19991224, December 1999, 469 . 471 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 472 Jensen, "HTTP Extensions for Distributed Authoring -- 473 WEBDAV", RFC 2518, February 1999. 475 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 476 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 477 March 2007. 479 [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) 480 Configuration Access Protocol (XCAP)", RFC 4825, May 2007. 482 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 483 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 485 [RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 486 Publishing Protocol", RFC 5023, October 2007. 488 [draft-whitehead-http-etag] 489 Whitehead, J., "Design Considerations for State 490 Identifiers in HTTP and WebDAV", 491 draft-whitehead-http-etag-00 (work in progress), 492 February 2006. 494 (As of November 2006, there didn't appear to be any 495 activity related to this draft.) 497 URIs 499 [1] 501 [2] 503 Appendix A. Use Cases 505 A.1. Simple Authoring 507 Let us consider a server not having the quality of preserving octet- 508 by-octet identity, for instance because of SVN-style keyword 509 expansion in text content (). 512 In this case, the client has previously retrieved the representation 513 for , and the server has returned the ETag 514 "1": 516 >> Request (1) 518 GET /test HTTP/1.1 519 Host: example.com 521 >> Response (1) 523 HTTP/1.1 200 OK 524 Content-Type: text/plain 525 ETag: "1" 527 # $Revision: 1 $ 528 Sample text. 530 The client now wants to update the resource. To avoid overwriting 531 somebody else's changes, it submits the PUT request with the HTTP 532 "If-Match" request header (see [RFC2616], Section 14.24): 534 >> Request (2) 536 PUT /test HTTP/1.1 537 Host: example.com 538 If-Match: "1" 540 # $Revision: 1 $ 541 New sample text. 543 If the resource was modified in the meantime, the server will reject 544 the request with a 412 Precondition Failed status: 546 >> Response (2a) 548 HTTP/1.1 412 Precondition Failed 549 Content-Type: text/plain 551 Precondition Failed: entity tag supplied in If-Match request header 552 did not match current. 554 In this case, the client usually has take care of merging the changes 555 made locally with those made on the server ("Merge Conflict"). 557 If there was no overlapping update, the server will execute the 558 request and return a new entity tag: 560 >> Response (2b) 562 HTTP/1.1 200 OK 563 Content-Type: text/plain 564 ETag: "2" 566 Note however, that at this point the client knows the new entity tag, 567 but doesn not know the current representation, which will have been 568 updated by the server to: 570 # $Revision: 2 $ 571 New sample text. 573 What seems to be a problem at first may not be a real problem in 574 practice. Let us assume that the client continues editing the 575 resource, using the entity tag obtained from the previous request, 576 but editing the entity it last sent: 578 >> Request (3) 580 PUT /test HTTP/1.1 581 Host: example.com 582 If-Match: "2" 584 # $Revision: 1 $ 585 A third attempt. 587 Assuming there was no overlapping update, the PUT request will 588 succeed: 590 >> Response (3) 592 HTTP/1.1 200 OK 593 Content-Type: text/plain 594 ETag: "3" 596 Note that the only problem here is that the client doesn't have an 597 exact copy of the entity it is editing. However, from the server's 598 point of view this is entirely irrelevant, because the "Revision" 599 keyword will be automatically updated upon every write anyway. 601 In any case, the final contents will be: 603 # $Revision: 3 $ 604 A third attempt. 606 A.2. Simple Authoring, with Entity-Transform header 608 In the example above (Appendix A.1, Response 2b), the server returns 609 an ETag response header upon PUT, although the content actually was 610 rewritten due to keyword substitution. 612 A server implementing this specification would instead respond with: 614 >> Response (2c) 616 HTTP/1.1 200 OK 617 Content-Type: text/plain 618 ETag: "2" 619 Entity-Transform: unspecified "2" 621 This indicates that the content that was sent is not octet-by-octet 622 identical to what a subsequent GET request would retrieve. It is 623 then up to the client to decide whether it wants to re-fetch the 624 content before continuing edits. 626 A.3. Setting both Content and Metadata 628 In this example, the server exposes data extracted from the HTML 629 element ([HTML], Section 7.4.2) as a custom WebDAV property 630 ([RFC4918], Section 4), allowing both read and write access. 632 In the first step, the client obtains the current representation for 633 <http://example.com/test.html>: 635 >> Request (1) 637 GET /test.html HTTP/1.1 638 Host: example.com 640 >> Response (1) 642 HTTP/1.1 200 OK 643 Content-Type: text/html 644 ETag: "A" 646 <html> 647 <head> 648 </head> 649 <body> 650 </body> 651 </html> 653 Next, it adds one paragraph to the <body> element, and gets back a 654 new entity tag: 656 >> Request (2) 658 PUT /test.html HTTP/1.1 659 Host: example.com 660 If-Match: "A" 662 <html> 663 <head> 664 </head> 665 <body> 666 <p>First paragraph.</p> 667 </body> 668 </html> 670 >> Response (2) 672 HTTP/1.1 200 OK 673 ETag: "B" 674 Next, the client sets a custom "title" property (see [RFC4918], 675 Section 9.2): 677 >> Request (3) 679 PROPPATCH /test.html HTTP/1.1 680 Host: example.com 681 Content-Type: application/xml 683 <proppatch xmlns="DAV:"> 684 <set> 685 <prop> 686 <title xmlns="http://ns.example.org/" 687 >A sample document 688 689 690 692 >> Response (3) 694 HTTP/1.1 207 Multi-Status 695 Content-Type: application/xml 697 698 699 /test.html 700 701 702 703 </prop> 704 <status>HTTP/1.1 2OO OK</status> 705 </propstat> 706 </response> 707 </multistatus> 709 The server knows how to propagate property changes into the HTML 710 content, so it updates the entity by adding an HTML title document 711 accordingly. This causes the entity tag changing to "C". 713 The new entity body is shown below, but the client does not realize 714 that it did change at all. 716 <html> 717 <head> 718 <title>A sample document 719 720 721

First paragraph.

722 723 725 A subsequent attempt by the client to update the entity body will 726 fail, unless it realizes that changing WebDAV properties may affect 727 the entity as well. In this case, it would have had to get the 728 current entity tag before proceeding. Of course, this introduces an 729 additional round-trip, and a timing window during which overlapping 730 updates by other clients would go unnoticed. 732 Note that a client would be affected by this behaviour even in the 733 presence of an exclusive WebDAV write lock (see [RFC4918], Section 734 7). 736 A.4. Setting both Content and Metadata, new style 738 Below we repeat the example from above (Appendix A.3), but here the 739 origin server returns entity tags for all write operations, and the 740 user agent knows how to deal with them. That is, both take advantage 741 of what [RFC2616] already allows. 743 >> Request (3) 745 PROPPATCH /test.html HTTP/1.1 746 Host: example.com 747 Content-Type: application/xml 749 750 751 752 753 A sample document 754 755 756 757 758 >> Response (3) 760 HTTP/1.1 207 Multi-Status 761 Content-Type: application/xml 762 ETag: "C" 764 765 766 /test.html 767 768 769 770 </prop> 771 <status>HTTP/1.1 2OO OK</status> 772 </propstat> 773 </response> 774 </multistatus> 776 As before, this causes the entity to change, and a new entity tag to 777 be assigned. But in this case, the origin server actually notifies 778 the client of the changed state by including the "ETag" response 779 header. 781 The client now will be aware that the requested entity change, and 782 can use the new entity tag in subsequent requests (potentially after 783 refreshing the local copy). 785 Appendix B. Change Log (to be removed by RFC Editor before publication) 787 B.1. Since draft-reschke-http-etag-on-write-00 789 Add and resolves issues "entity-header" and "extensibility", by 790 removing the extension hooks, and by redefining the header to it can 791 be used as an Entity header. 793 B.2. Since draft-reschke-http-etag-on-write-01 795 Update APP and CALDAV references. Remove RFC3986 reference (not 796 needed anymore after the simplication in draft 01). Fix typo in 797 header description ("submitted entity", not "stored entity"). Remove 798 comparison about how XCAP and CALDAV profile RFC2616: after all, both 799 mandate a behaviour that was legal but optional before. Add 800 "Updates: RFC2616". 802 B.3. Since draft-reschke-http-etag-on-write-02 804 In the references, note that there was no activitiy on 805 draft-whitehead-http-etag-00 anymore. Change intended status to 806 "Experimental". Update APP reference. Update statements about 807 current status of XCAP and CALDAV. Add and resolve "clarify- 808 extension". 810 B.4. Since draft-reschke-http-etag-on-write-03 812 Update XCAP reference. Update header definition to use prose rules 813 rather than comments. Clarify "identity" keyword when appearing with 814 a weak entity-tag. In PROPPATCH/HTML example, fix whitespace so that 815 the HTML title element has exactly the same value as the one that was 816 PROPPATCHed. Mention that ETags changing due to a PROPPATCH could 817 even occur in presence of a WebDAV write lock. Expand keyword 818 substitution example with variant where Entity-Transform is returned. 820 B.5. Since draft-reschke-http-etag-on-write-04 822 Update APP reference. Update CalDAV reference (published as 823 RFC4791). Update "prior work" (RFC4791 being published, XCAP having 824 been approved). 826 B.6. Since draft-reschke-http-etag-on-write-05 828 Update XCAP reference (published as RFC4825). Update "prior work" 829 (RFC4825 being published). 831 B.7. Since draft-reschke-http-etag-on-write-06 833 Replace RFC2518 references with RFC4918 where appropriate. Update 834 APP reference. 836 B.8. Since draft-reschke-http-etag-on-write-07 838 Update APP reference. Reference the "requested variant" issue on the 839 RFC2616bis issues list 840 (<http://www.w3.org/Protocols/HTTP/1.1/rfc2616bis/issues/#i69>). 842 Appendix C. Open issues (to be removed by RFC Editor prior to 843 publication) 845 C.1. edit 847 Type: edit 848 julian.reschke@greenbytes.de (2006-08-10): Umbrella issue for 849 editorial fixes/enhancements. 851 Author's Address 853 Julian F. Reschke 854 greenbytes GmbH 855 Hafenweg 16 856 Muenster, NW 48155 857 Germany 859 Phone: +49 251 2807760 860 Email: julian.reschke@greenbytes.de 861 URI: http://greenbytes.de/tech/webdav/ 863 Full Copyright Statement 865 Copyright (C) The IETF Trust (2007). 867 This document is subject to the rights, licenses and restrictions 868 contained in BCP 78, and except as set forth therein, the authors 869 retain all their rights. 871 This document and the information contained herein are provided on an 872 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 873 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 874 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 875 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 876 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 877 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 879 Intellectual Property 881 The IETF takes no position regarding the validity or scope of any 882 Intellectual Property Rights or other rights that might be claimed to 883 pertain to the implementation or use of the technology described in 884 this document or the extent to which any license under such rights 885 might or might not be available; nor does it represent that it has 886 made any independent effort to identify any such rights. Information 887 on the procedures with respect to rights in RFC documents can be 888 found in BCP 78 and BCP 79. 890 Copies of IPR disclosures made to the IETF Secretariat and any 891 assurances of licenses to be made available, or the result of an 892 attempt made to obtain a general license or permission for the use of 893 such proprietary rights by implementers or users of this 894 specification can be obtained from the IETF on-line IPR repository at 895 http://www.ietf.org/ipr. 897 The IETF invites any interested party to bring to its attention any 898 copyrights, patents or patent applications, or other proprietary 899 rights that may cover technology that may be required to implement 900 this standard. Please address the information to the IETF at 901 ietf-ipr@ietf.org. 903 Acknowledgment 905 Funding for the RFC Editor function is provided by the IETF 906 Administrative Support Activity (IASA).