idnits 2.17.1 draft-reschke-http-etag-on-write-03.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 830. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 841. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 848. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 854. ** 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 (October 16, 2006) is 6402 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) == Outdated reference: A later version (-17) exists of draft-ietf-atompub-protocol-11 -- 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) October 16, 2006 5 Intended status: Experimental 6 Expires: April 19, 2007 8 The Hypertext Transfer Protocol (HTTP) Entity Tag ("ETag") 9 Response Header in Write Operations 10 draft-reschke-http-etag-on-write-03 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 19, 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 . . . . . . . . . . . . . . . . . . . . . . . . . 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. 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 B.3. Since draft-reschke-http-etag-on-write-02 . . . . . . . . 18 96 Appendix C. Resolved issues (to be removed by RFC Editor 97 before publication) . . . . . . . . . . . . . . . . . 18 98 C.1. clarify-extensibility . . . . . . . . . . . . . . . . . . 18 99 Appendix D. Open issues (to be removed by RFC Editor prior to 100 publication) . . . . . . . . . . . . . . . . . . . . 19 101 D.1. edit . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 102 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19 103 Intellectual Property and Copyright Statements . . . . . . . . . . 20 105 1. Introduction 107 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 108 called "Entity Tag", to be returned in the "ETag" response header 109 (see [RFC2616], Section 14.19). However, the description of this 110 header for write operations such as PUT is incomplete, and has caused 111 confusion among developers and protocol designers, and potentially 112 interoperability problems. 114 This document explains the problem in detail and suggests both a 115 clarification for a revision to [RFC2616] and a new header for use in 116 responses, making HTTP entity tags more useful for user agents that 117 want to avoid round-trips to the server after modifying a resource. 119 1.1. Questions out of Scope 121 Note that there is a related problem: modifying content-negotiated 122 resources. Here the consensus seems to be simply not to do it. 123 Instead, the origin server should reveal specific URIs of content 124 that is not content-negotiated in the Content-Location response 125 header ([RFC2616], Section 14.14), and user agents should use this 126 more specific URI for authoring. Thus, the remainder of this 127 document will focus on resources for which no content negotiation 128 takes place. 130 Another related question is the usability of the weak entity tags for 131 authoring (see [RFC2616], Section 13.3.3). Although this document 132 focuses on the usage of strong entity tags, it is believed that the 133 changes suggested in this document could be applied to weak entity 134 tags as well. 136 1.2. The Interoperability Problem 138 For a long time, nobody realized that there was a problem at all, or 139 those who realized preferred to ignore it. 141 Server implementers added code that would return the new value of the 142 "ETag" header in a response to a successful PUT request. After all, 143 the client could be interested in it. 145 User agent developers in turn were happy to get a new "ETag" value, 146 saving a subsequent HEAD request to retrieve the new entity tag. 148 However, at some point of time, potentially during a Web Distributed 149 Authoring and Versioning (WebDAV, [RFC2518]) interoperability event, 150 client programmers asked server programmers to always return "ETag" 151 headers upon PUT, never ever to change the entity tag without "good 152 reason", and - by the way - always to guarantee that the server 153 stores the new content octet-by-octet. 155 From the perspective of client software that wants to treat an HTTP 156 server as a file system replacement, this makes a lot of sense. 157 After all, when one writes to a file one usually expects the file 158 system to store what was written, and not to unexpectedly change the 159 contents. 161 However, in general, an HTTP server is not a file system replacement. 162 There may be some that have been designed that way, and some that 163 expose some parts of their namespace that have this quality. But in 164 general, HTTP server implementers have a lot of freedom in how 165 resources are implemented. Indeed, this flexibility is one of the 166 reasons for HTTP's success, allowing it to be used for a wide range 167 of tasks, of which replacing file systems is just one (and not 168 necessarily the most interesting one). 170 In particular: 172 o A server may not store a resource as a binary object - in this 173 case, the representation returned in a subsequent GET request may 174 just be similar, but not identical to what was written. Good 175 examples are servers that use HTTP to access XML data ([XCAP]), 176 Calendaring data ([CALDAV]) or newsfeed data ([APP]). 178 o A server may change the data being written on purpose, while it's 179 being written. Examples that immediately come to mind are keyword 180 substitution in a source control system, or filters that remove 181 potentially insecure parts out of HTML pages. 183 Furthermore: 185 o An "unrelated" method such as WebDAV's PROPPATCH (see [RFC2518], 186 Section 8.2) may affect the entity body and therefore the entity 187 tag in an unexpected way, because the server stores some or all of 188 the WebDAV properties inside the entity body (for instance, GPS 189 information inside a JPG image file). 191 As long as servers store the content octet-by-octet, and return 192 exactly what the client wrote, there is no problem at all. 194 Things get more interesting when a server does change the content, 195 such as in the "simple authoring" example given in Appendix A.1. 196 Here, the server does change the content upon writing to the 197 resource, yet no harm is done, because the final state of the 198 resource on the server does not depend on the client being aware of 199 that. 201 All of the content rewriting examples mentioned above have this 202 quality: the client can safely continue to edit the entity it sent, 203 because the result of the transformation done by the server will be 204 the same in the end. Formally, if we call the server-side 205 transformation "t", the initial content "c", and the client-side 206 editing steps "e1" and "e2", then 208 t(e2(e1(c))) = t(e2(t(e1(c)))) 210 e.g., it's irrelevant whether the client obtained the current entity 211 body before doing its second edit. 213 [[example.for.non.safe.rewrite: Question: does anybody know a real- 214 world example for server-side content rewriting where the above is 215 not true? --julian.reschke@greenbytes.de]] 217 Problems will only occur if the client uses the entity body it sent, 218 and the entity tag it obtained in return, in subsequent requests that 219 only transfer part of the entity body, such as GET or PUT requests 220 using the "Range" request header (see [RFC2616], Section 14.35). 222 Furthermore, some clients need to expose the actual contents to the 223 end user. These clients will have to ensure that they really have 224 the current representation. 226 Entity bodies (and thus entity tags) changing due to side effects of 227 seemingly unrelated requests are indeed a problem, as demonstrated in 228 Appendix A.2, and this specification proposes a way to resolve this 229 in Section 3. 231 1.3. Analysis of RFC2616's Definitions 233 There are several places in the HTTP/1.1 specification ([RFC2616]) 234 mentioning the "ETag" response header. 236 Let us start with the header definition in Section 14.19: 238 The ETag response-header field provides the current value of the 239 entity tag for the requested variant. Sections 14.24, 14.26 and 240 14.44 describe the headers used with entity tags. The entity tag 241 MAY be used for comparison with other entities from the same 242 resource (see Section 13.3.3). 244 The meaning of a "response-header" in turn is defined in Section 6.2: 246 The response-header fields allow the server to pass additional 247 information about the response which cannot be placed in the 248 Status-Line. These header fields give information about the 249 server and about further access to the resource identified by the 250 Request-URI. 252 The "ETag" response header itself is mentioned mainly in the context 253 of cache validation, such as in Section 13.3.2. What is missing is a 254 coherent description on how the origin server can notify the user- 255 agent when the entity tag changes as result of a write operation, 256 such as PUT. 258 Indeed, the definition of the 201 Created status code mentions entity 259 tags (Section 10.2.2): 261 A 201 response MAY contain an ETag response header field 262 indicating the current value of the entity tag for the requested 263 variant just created, see Section 14.19. 265 The "ETag" response header is mentioned again in the definition of 266 206 Partial Content (Section 10.2.7) and 304 Not Modified (Section 267 10.3.5), but notably missing are statements about other 2xx series 268 status codes that can occur upon a successful PUT operation, such as 269 200 OK (Section 10.2.1) and 204 No Content (Section 10.2.5). 271 Summarizing, the specification is a bit vague about what an ETag 272 response header upon a write operation means, but this problem is 273 somewhat mitigated by the precise definition of a response header. A 274 proposal for enhancing [RFC2616] in this regard is made in Section 3 275 below. 277 1.4. Prior Work 279 While working on the revision of [RFC2518], the IETF WebDAV working 280 group realized that this is a generic problem that needs attention 281 independently of WebDAV. An initial attempt was made with 282 [draft-whitehead-http-etag] in February 2006, but no progress was 283 made since. 285 At the time of this writing in October 2006, two specifications based 286 on HTTP were either under IESG review or just approved by the IESG, 287 taking two opposite approaches: 289 o Section 8.5 of [XCAP] makes it a MUST-level requirement to return 290 an entity tag upon PUT, even though the very nature of an XCAP 291 server will cause it to rewrite contents (due to its XML-based 292 storage). 294 o Section 5.3.4 of [CALDAV] explicitly forbids ("MUST NOT") 295 returning an entity tag upon PUT if the content was rewritten. 297 In essence, this makes it impossible to implement an HTTP resource 298 that conforms to both specifications. Due to the differing use cases 299 of XCAP and CalDAV, this may not be a problem in practice, but the 300 disagreement in itself is scary. Publication of these specifications 301 on the standards track will make it much harder for future protocols 302 to deal with this topic in a meaningful way (comments were sent 303 during IETF Last Call for CalDAV, see 304 ). 306 2. Notational Conventions 308 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 309 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 310 document are to be interpreted as described in [RFC2119]. 312 The terminology used here follows and extends that in the HTTP 313 specification [RFC2616], notably the augmented Backus-Naur Form (BNF) 314 defined in Section 2.1 of that document. 316 3. Clarifications on the Behavior of the 'ETag' Response Header 318 This section describes a minimal change to [RFC2616], proposed in . 321 At the end of Section 10.2 of [RFC2616], add: 323 The response MAY contain an ETag response header field indicating 324 the current value of the entity tag (Section 14.19) for the 325 requested variant. The value SHOULD be the same as the one 326 returned upon a subsequent HEAD request addressing the same 327 variant. 329 In Section 10.2.1 of [RFC2616], remove: 331 A 201 response MAY contain an ETag response header field 332 indicating the current value of the entity tag for the requested 333 variant just created, see Section 14.19. 335 In essence, this moves the statement about entity tags in write 336 operations from the specific case of status 201 Created into the more 337 generic description of the 2xx series status codes. 339 [[rcf2616.enhancements: Should "requested variant" be clarified in 340 the context of write operations? --julian.reschke@greenbytes.de]] 342 4. The 'Entity-Transform' Header 344 The 'Entity-Transform' entity header provides information about 345 whether a transformation has been applied to an entity body. 347 When used in an HTTP request, its meaning is undefined. In an HTTP 348 response, it provides information whether the server has applied a 349 transformation when the entity was stored last. 351 In general, entity headers may be stored in intermediates. The main 352 use of this header however applies to the HTTP PUT method, of which 353 by default the results are not cacheable (see [RFC2616], Section 354 9.6). In addition, the value format is defined so that a client can 355 reliably detect whether the information is fresh. 357 Format: 359 Entity-Transform = "Entity-Transform" ":" entity-transform-spec 360 entity-transform-spec = entity-transform-keyword SP entity-tag 361 entity-transform-keyword = "identity" | "unspecified"| token 362 ; entity-tag: defined in [RFC2616], Section 3.11 363 ; token: defined in [RFC2616], Section 2.2 365 The entity-tag specifies the entity body to which this information 366 applies. 368 An entity-transform-keyword of "identity" specifies that the origin 369 server has stored the entity octet-by-octet, thus the user agent MAY 370 use a local copy of the entity body with the given entity-tag for 371 subsequent requests that rely on octet-by-octet identity (such as a 372 PUT with "Range" request header). 374 Both the absence of this response header and any entity-transform- 375 keyword value other than "identity" specify that the origin server 376 may have transformed the entity before storage, thus a subsequent 377 retrieval will not necessarily return an exact copy of the submitted 378 entity. 380 Note: usage of keywords other than "identity" or "unspecified" is 381 reserved for future revisisions of this specification. 383 4.1. Examples 385 Content was stored octet-by-octet: 387 HTTP/1.1 200 OK 388 ETag: "1" 389 Entity-Transform: identity "1" 391 Content was transformed: 393 HTTP/1.1 200 OK 394 ETag: "2" 395 Entity-Transform: unspecified "2" 397 Response containing a stale "Entity-Transform" header: 399 HTTP/1.1 200 OK 400 ETag: "3" 401 Entity-Transform: unspecified "2" 403 Note that in this case the newly assigned entity tag and the entity 404 tag returned in "Entity-Transform" do not match, thus the client is 405 aware that the header value is stale and can't be used. 407 5. How This Helps 409 The clarification of [RFC2616] (see Section 3) makes it clear that 410 user agents can use "ETag" headers obtained in write operations, as 411 long as they do not require octet-by-octet identity. In particular, 412 a new entity tag can be returned for any method, such as a WebDAV 413 PROPPATCH (see [RFC2518], Section 8.2. This helps dealing with the 414 problem described in Appendix A.2. See Appendix A.3 for details. 416 The addition of the "Entity-Transform" header (see Section 4) enables 417 origin servers to signal that they stored an exact copy of the 418 content, thus allowing clients not to refetch the content. Note that 419 by default (in absence of the response header), a client can not make 420 any assumptions about the server's behavior in this regard. Thus 421 clients will only benefit from new servers explicitly setting the new 422 header. 424 6. IANA Considerations 426 This document specifies the new HTTP header listed below. 428 Header field name: Entity-Transform 430 Applicable protocol: http 432 Status: informational 434 Author/Change controller: IETF 436 Specification document: Section 4 of this specification 438 7. Security Considerations 440 This specification introduces no new security considerations beyond 441 those discussed in Section 15 of [RFC2616]. 443 8. References 445 8.1. Normative References 447 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 448 Requirement Levels", BCP 14, RFC 2119, March 1997. 450 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 451 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 452 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 454 8.2. Informative References 456 [APP] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 457 Publishing Protocol", draft-ietf-atompub-protocol-11 (work 458 in progress), October 2006. 460 [CALDAV] Daboo, C., Desruisseaux, B., and L. Dusseault, 461 "Calendaring Extensions to WebDAV (CalDAV)", 462 draft-dusseault-caldav-15 (work in progress), 463 September 2006. 465 [HTML] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 466 Specification", W3C REC-html401-19991224, December 1999, 467 . 469 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 470 Jensen, "HTTP Extensions for Distributed Authoring -- 471 WEBDAV", RFC 2518, February 1999. 473 [XCAP] Rosenberg, J., "The Extensible Markup Language (XML) 474 Configuration Access Protocol (XCAP)", 475 draft-ietf-simple-xcap-11 (work in progress), May 2006. 477 [draft-whitehead-http-etag] 478 Whitehead, J., "Design Considerations for State 479 Identifiers in HTTP and WebDAV", 480 draft-whitehead-http-etag-00 (work in progress), 481 February 2006. 483 (As of October 2006, there didn't appear to be any 484 activity related to this draft.) 486 URIs 488 [1] 490 [2] 492 Appendix A. Use Cases 494 A.1. Simple Authoring 496 Let us consider a server not having the quality of preserving octet- 497 by-octet identity, for instance because of SVN-style keyword 498 expansion in text content (). 501 In this case, the client has previously retrieved the representation 502 for , and the server has returned the ETag 503 "1": 505 >> Request (1) 507 GET /test HTTP/1.1 508 Host: example.com 510 >> Response (1) 512 HTTP/1.1 200 OK 513 Content-Type: text/plain 514 ETag: "1" 516 # $Revision: 1 $ 517 Sample text. 519 The client now wants to update the resource. To avoid overwriting 520 somebody else's changes, it submits the PUT request with the HTTP 521 "If-Match" request header (see [RFC2616], Section 14.24): 523 >> Request (2) 525 PUT /test HTTP/1.1 526 Host: example.com 527 If-Match: "1" 529 # $Revision: 1 $ 530 New sample text. 532 If the resource was modified in the meantime, the server will reject 533 the request with a 412 Precondition Failed status: 535 >> Response (2a) 537 HTTP/1.1 412 Precondition Failed 538 Content-Type: text/plain 540 Precondition Failed: entity tag supplied in If-Match request header 541 did not match current. 543 In this case, the client usually has take care of merging the changes 544 made locally with those made on the server ("Merge Conflict"). 546 If there was no overlapping update, the server will execute the 547 request and return a new entity tag: 549 >> Response (2b) 551 HTTP/1.1 200 OK 552 Content-Type: text/plain 553 ETag: "2" 555 Note however, that at this point the client knows the new entity tag, 556 but doesn not know the current representation, which will have been 557 updated by the server to: 559 # $Revision: 2 $ 560 New sample text. 562 What seems to be a problem at first may not be a real problem in 563 practice. Let us assume that the client continues editing the 564 resource, using the entity tag obtained from the previous request, 565 but editing the entity it last sent: 567 >> Request (3) 569 PUT /test HTTP/1.1 570 Host: example.com 571 If-Match: "2" 573 # $Revision: 1 $ 574 A third attempt. 576 Assuming there was no overlapping update, the PUT request will 577 succeed: 579 >> Response (3) 581 HTTP/1.1 200 OK 582 Content-Type: text/plain 583 ETag: "3" 585 Note that the only problem here is that the client doesn't have an 586 exact copy of the entity it's editing. However, from the server's 587 point of view this is entirely irrelevant, because the "Revision" 588 keyword will be automatically updated upon every write anyway. 590 In any case, the final contents will be: 592 # $Revision: 3 $ 593 A third attempt. 595 A.2. Setting both Content and Metadata 597 In this example, the server exposes data extracted from the HTML 598 element ([HTML], Section 7.4.2) as a custom WebDAV property 599 ([RFC2518], Section 4), allowing both read and write access. 601 In the first step, the client obtains the current representation for 602 <http://example.com/test.html>: 604 >> Request (1) 606 GET /test.html HTTP/1.1 607 Host: example.com 608 >> Response (1) 610 HTTP/1.1 200 OK 611 Content-Type: text/html 612 ETag: "A" 614 <html> 615 <head> 616 </head> 617 <body> 618 </body> 619 </html> 621 Next, it adds one paragraph to the <body> element, and gets back a 622 new entity tag: 624 >> Request (2) 626 PUT /test.html HTTP/1.1 627 Host: example.com 628 If-Match: "A" 630 <html> 631 <head> 632 </head> 633 <body> 634 <p>First paragraph.</p> 635 </body> 636 </html> 638 >> Response (2) 640 HTTP/1.1 200 OK 641 ETag: "B" 643 Next, the client sets a custom "title" property (see [RFC2518], 644 Section 8.2): 646 >> Request (3) 648 PROPPATCH /test.html HTTP/1.1 649 Host: example.com 650 Content-Type: application/xml 652 <proppatch xmlns="DAV:"> 653 <set> 654 <prop> 655 <title xmlns="http://ns.example.org/"> 656 A sample document 657 658 659 660 662 >> Response (3) 664 HTTP/1.1 207 Multi-Status 665 Content-Type: application/xml 667 668 669 /test.html 670 671 672 673 </prop> 674 <status>HTTP/1.1 2OO OK</status> 675 </propstat> 676 </response> 677 </multistatus> 679 The server knows how to propagate property changes into the HTML 680 content, so it updates the entity by adding an HTML title document 681 accordingly. This causes the entity tag changing to "C". 683 The new entity body is shown below, but the client does not realize 684 that it did change at all. 686 <html> 687 <head> 688 <title>A sample document 689 690 691

First paragraph.

692 693 694 A subsequent attempt by the client to update the entity body will 695 fail, unless it realizes that changing WebDAV properties may affect 696 the entity as well. In this case, it would have had to get the 697 current entity tag before proceeding. Of course, this introduces an 698 additional round-trip, and a timing window during which overlapping 699 updates by other clients would go unnoticed. 701 A.3. Setting both Content and Metadata, new style 703 Below we repeat the example from above (Appendix A.2), but here the 704 origin server returns entity tags for all write operations, and the 705 user agent knows how to deal with them. That is, both take advantage 706 of [RFC2616] already allows. 708 >> Request (3) 710 PROPPATCH /test.html HTTP/1.1 711 Host: example.com 712 Content-Type: application/xml 714 715 716 717 718 A sample document 719 720 721 722 724 >> Response (3) 726 HTTP/1.1 207 Multi-Status 727 Content-Type: application/xml 728 ETag: "C" 730 731 732 /test.html 733 734 735 736 </prop> 737 <status>HTTP/1.1 2OO OK</status> 738 </propstat> 739 </response> 740 </multistatus> 741 As before, this causes the entity to change, and a new entity tag to 742 be assigned. But in this case, the origin server actually notifies 743 the client of the changed state by including the "ETag" response 744 header. 746 The client now will be aware that the requested entity change, and 747 can use the new entity tag in subsequent requests (potentially after 748 refreshing the local copy). 750 Appendix B. Change Log (to be removed by RFC Editor before publication) 752 B.1. Since draft-reschke-http-etag-on-write-00 754 Add and resolves issues "entity-header" and "extensibility", by 755 removing the extension hooks, and by redefining the header to it can 756 be used as an Entity header. 758 B.2. Since draft-reschke-http-etag-on-write-01 760 Update APP and CALDAV references. Remove RFC3986 reference (not 761 needed anymore after the simplication in draft 01). Fix typo in 762 header description ("submitted entity", not "stored entity"). Remove 763 comparison about how XCAP and CALDAV profile RFC2616: after all, both 764 mandate a behaviour that was legal but optional before. Add 765 "Updates: RFC2616". 767 B.3. Since draft-reschke-http-etag-on-write-02 769 In the references, note that there was no activitiy on 770 draft-whitehead-http-etag-00 anymore. Change intended status to 771 "Experimental". Update APP reference. Update statements about 772 current status of XCAP and CALDAV. Add and resolve "clarify- 773 extension". 775 Appendix C. Resolved issues (to be removed by RFC Editor before 776 publication) 778 Issues that were either rejected or resolved in this version of this 779 document. 781 C.1. clarify-extensibility 783 Type: edit 785 julian.reschke@greenbytes.de (2006-10-12): Clarify the extension 786 point. 788 Resolution (2006-10-12): Clarify that future revisions of this 789 specification may define keywords other than the two defined here, 790 and that the only one specifiying octet-by-octet equivalence is 791 "identity". 793 Appendix D. Open issues (to be removed by RFC Editor prior to 794 publication) 796 D.1. edit 798 Type: edit 800 julian.reschke@greenbytes.de (2006-08-10): Umbrella issue for 801 editorial fixes/enhancements. 803 Author's Address 805 Julian F. Reschke 806 greenbytes GmbH 807 Hafenweg 16 808 Muenster, NW 48155 809 Germany 811 Phone: +49 251 2807760 812 Fax: +49 251 2807761 813 Email: julian.reschke@greenbytes.de 814 URI: http://greenbytes.de/tech/webdav/ 816 Full Copyright Statement 818 Copyright (C) The Internet Society (2006). 820 This document is subject to the rights, licenses and restrictions 821 contained in BCP 78, and except as set forth therein, the authors 822 retain all their rights. 824 This document and the information contained herein are provided on an 825 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 826 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 827 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 828 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 829 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 830 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 832 Intellectual Property 834 The IETF takes no position regarding the validity or scope of any 835 Intellectual Property Rights or other rights that might be claimed to 836 pertain to the implementation or use of the technology described in 837 this document or the extent to which any license under such rights 838 might or might not be available; nor does it represent that it has 839 made any independent effort to identify any such rights. Information 840 on the procedures with respect to rights in RFC documents can be 841 found in BCP 78 and BCP 79. 843 Copies of IPR disclosures made to the IETF Secretariat and any 844 assurances of licenses to be made available, or the result of an 845 attempt made to obtain a general license or permission for the use of 846 such proprietary rights by implementers or users of this 847 specification can be obtained from the IETF on-line IPR repository at 848 http://www.ietf.org/ipr. 850 The IETF invites any interested party to bring to its attention any 851 copyrights, patents or patent applications, or other proprietary 852 rights that may cover technology that may be required to implement 853 this standard. Please address the information to the IETF at 854 ietf-ipr@ietf.org. 856 Acknowledgment 858 Funding for the RFC Editor function is provided by the IETF 859 Administrative Support Activity (IASA).