idnits 2.17.1 draft-reschke-http-etag-on-write-00.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 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 753. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 764. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 771. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 777. ** 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. 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). -- 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 (August 9, 2006) is 6463 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-09 == Outdated reference: A later version (-15) exists of draft-dusseault-caldav-13 -- 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 (~~), 5 warnings (==), 9 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 Intended status: Informational August 9, 2006 5 Expires: February 10, 2007 7 The Hypertext Transfer Protocol (HTTP) Entity Tag ("ETag") 8 Response Header in Write Operations 9 draft-reschke-http-etag-on-write-00 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on February 10, 2007. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 43 called "Entity Tag", to be returned in the "ETag" response header. 44 However, the description of this header for write operations such as 45 PUT is incomplete, and has caused confusion among developers and 46 protocol designers, and potentially interoperability problems. 48 This document explains the problem in detail and suggests both a 49 clarification for a revision to the HTTP/1.1 specification (RFC2616) 50 and a new response header, making HTTP entity tags more useful for 51 user agents that want to avoid round-trips to the server after 52 modifying a resource. 54 Editorial Note (To be removed by RFC Editor before publication) 56 Distribution of this document is unlimited. Please send comments to 57 the Hypertext Transfer Protocol (HTTP) mailing list at 58 ietf-http-wg@w3.org [1], which may be joined by sending a message 59 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 61 Discussions of the HTTP working group are archived at 62 . 64 XML versions, latest edits and the issues list for this document are 65 available from . 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 1.1. Questions out of Scope . . . . . . . . . . . . . . . . . . 4 72 1.2. The Interoperability Problem . . . . . . . . . . . . . . . 4 73 1.3. Analysis of RFC2616's Definitions . . . . . . . . . . . . 6 74 1.4. Prior Work . . . . . . . . . . . . . . . . . . . . . . . . 7 75 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 8 76 3. Clarifications on the Behavior of the 'ETag' Response 77 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 78 4. The 'Entity-Transform' Response Header . . . . . . . . . . . . 9 79 4.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 5. How This Helps . . . . . . . . . . . . . . . . . . . . . . . . 10 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 83 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 84 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 85 8.2. Informative References . . . . . . . . . . . . . . . . . . 11 86 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . . 12 87 A.1. Simple Authoring . . . . . . . . . . . . . . . . . . . . . 12 88 A.2. Setting both Content and Metadata . . . . . . . . . . . . 14 89 A.3. Setting both Content and Metadata, new style . . . . . . . 16 90 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 17 91 Intellectual Property and Copyright Statements . . . . . . . . . . 19 93 1. Introduction 95 The Hypertext Transfer Protocol (HTTP) specifies a state identifier, 96 called "Entity Tag", to be returned in the "ETag" response header 97 (see [RFC2616], Section 14.19). However, the description of this 98 header for write operations such as PUT is incomplete, and has caused 99 confusion among developers and protocol designers, and potentially 100 interoperability problems. 102 This document explains the problem in detail and suggests both a 103 clarification for a revision to [RFC2616] and a new response header, 104 making HTTP entity tags more useful for user agents that want to 105 avoid round-trips to the server after modifying a resource. 107 1.1. Questions out of Scope 109 Note that there is a related problem: modifying content-negotiated 110 resources. Here the consensus seems to be simply not to do it. 111 Instead, the origin server should reveal specific URIs of content 112 that is not content-negotiated in the Content-Location response 113 header ([RFC2616], Section 14.14), and user agents should use this 114 more specific URI for authoring. Thus, the remainder of this 115 document will focus on resources for which no content negotiation 116 takes place. 118 Another related question is the usability of the weak entity tags for 119 authoring (see [RFC2616], Section 13.3.3). Although this document 120 focuses on the usage of strong entity tags, it is believed that the 121 changes suggested in this document could be applied to weak entity 122 tags as well. 124 1.2. The Interoperability Problem 126 For a long time, nobody realized that there was a problem at all, or 127 those who realized preferred to ignore it. 129 Server implementers added code that would return the new value of the 130 "ETag" header in a response to a successful PUT request. After all, 131 the client could be interested in it. 133 User agent developers in turn were happy to get a new "ETag" value, 134 saving a subsequent HEAD request to retrieve the new entity tag. 136 However, at some point of time, potentially during a Web Distributed 137 Authoring and Versioning (WebDAV, [RFC2518]) interoperability event, 138 client programmers asked servers to always return "ETag" headers upon 139 PUT, never ever to change the entity tag without "good reason", and - 140 by the way - always to guarantee that the server stores the new 141 content octet-by-octet. 143 From the perspective of client software that wants to treat an HTTP 144 server as a file system replacement, this makes a lot of sense. 145 After all, when one writes to a file one usually expects the file 146 system to store what was written, and not to unexpectedly change the 147 contents. 149 However, in general, an HTTP server is not a file system replacement. 150 There may be some that have been designed that way, and some that 151 expose some parts of their namespace that have this quality. But in 152 general, HTTP server implementers have a lot of freedom in how 153 resources are implemented. Indeed, this flexibility is one of the 154 reasons for HTTP's success, allowing to be used for a wide range of 155 tasks, of which replacing file systems is just one (and not 156 necessarily the most interesting one). 158 In particular: 160 o A server may not store a resource as a binary object - in this 161 case, the representation returned in a subsequent GET request may 162 just be similar, but not identical to what was written. Good 163 examples are servers that use HTTP to access XML data ([XCAP]), 164 Calendaring data ([CALDAV]) or newsfeed data ([APP]). 166 o A server may change the data being written on purpose, while it's 167 being written. Examples that immediately come to mind are keyword 168 substitution in a source control system, or filters that remove 169 potentially insecure parts out of HTML pages. 171 Furthermore: 173 o An "unrelated" method such as WebDAV's PROPPATCH (see [RFC2518], 174 Section 8.2) may affect the entity body and therefore the entity 175 tag in an unexpected way, because the server stores some or all of 176 the WebDAV properties inside the entity body (for instance, GPS 177 information inside a JPG image file). 179 As long as servers store the content octet-by-octet, and return 180 exactly what the client wrote, there is no problem at all. 182 Things get more interesting when a server does change the content, 183 such as in the "simple authoring" example given in Appendix A.1. 184 Here, the server does change the content upon writing to the 185 resource, yet no harm is done, because the final state of the 186 resource on the server does not depend on the client being aware of 187 that. 189 All of the content rewriting examples mentioned above have this 190 quality: the client can safely continue to edit the entity it sent, 191 because the result of the transformation done by the server will be 192 the same in the end. Formally, if we call the server-side 193 transformation "t", the initial content "c", and the client-side 194 editing steps "e1" and "e2", then 196 t(e2(e1(c))) = t(e2(t(e1(c)))) 198 e.g., it's irrelevant whether the client obtained the current entity 199 body before doing its second edit. 201 [[example.for.non.safe.rewrite: Question: does anybody know a real- 202 world example for server-side content rewriting where the above is 203 not true? --julian.reschke@greenbytes.de]] 205 Problems will only occur if the client uses the entity body it sent, 206 and the entity tag it obtained in return, in subsequent requests that 207 only transfer part of the entity body, such as GET or PUT requests 208 using the "Range" request header (see [RFC2616], Section 14.35). 210 Furthermore, some clients need to expose the actual contents to the 211 end user. These clients will have to ensure that they really have 212 the current representation. 214 Entity bodies (and thus entity tags) changing due to side effects of 215 seemingly unrelated requests are indeed a problem, as demonstrated in 216 Appendix A.2, and this specification proposes a way to resolve this 217 in Section 3. 219 1.3. Analysis of RFC2616's Definitions 221 There are several places in the HTTP/1.1 specification ([RFC2616]) 222 mentioning the "ETag" response header. 224 Let us start with the header definition in Section 14.19: 226 The ETag response-header field provides the current value of the 227 entity tag for the requested variant. Sections 14.24, 14.26 and 228 14.44 describe the headers used with entity tags. The entity tag 229 MAY be used for comparison with other entities from the same 230 resource (see Section 13.3.3). 232 The meaning of a "response-header" in turn is defined in Section 6.2: 234 The response-header fields allow the server to pass additional 235 information about the response which cannot be placed in the 236 Status-Line. These header fields give information about the 237 server and about further access to the resource identified by the 238 Request-URI. 240 The "ETag" response header itself is mentioned mainly in the context 241 of cache validation, such as in Section 13.3.2. What is missing is a 242 coherent description on how the origin server can notify the user- 243 agent when the entity tag changes as result of a write operation, 244 such as PUT. 246 Indeed, the definition of the 201 Created status code mentions entity 247 tags (Section 10.2.2): 249 A 201 response MAY contain an ETag response header field 250 indicating the current value of the entity tag for the requested 251 variant just created, see Section 14.19. 253 The "ETag" response header is mentioned again in the definition of 254 206 Partial Content (Section 10.2.7) and 304 Not Modified (Section 255 10.3.5), but notably missing are statements about other 2xx series 256 status codes that can occur upon a successful PUT operation, such as 257 200 OK (Section 10.2.1) and 204 No Content (Section 10.2.5). 259 Summarizing, the specification is a bit vague about what an ETag 260 response header upon a write operation means, but this problem is 261 somewhat mitigated by the precise definition of a response header. A 262 proposal for enhancing [RFC2616] in this regard is made in Section 3 263 below. 265 1.4. Prior Work 267 While working on the revision of [RFC2518], the IETF WebDAV working 268 group realized that this is a generic problem that needs attention 269 independently of WebDAV. An initial attempt was made with 270 [draft-whitehead-http-etag] in February 2006, but no progress was 271 made since. 273 At the time of this writing in August 2006, two specifications based 274 on HTTP were under IESG review, taking two opposite approaches: 276 o Section 8.5 of [XCAP] makes it a MUST-level requirement to return 277 an entity tag upon PUT, even though the very nature of an XCAP 278 server will cause it to rewrite contents (due to its XML-based 279 storage). 281 o Section 5.3.4 of [CALDAV] explicitly forbids ("MUST NOT") 282 returning an entity tag upon PUT if the content was rewritten. 284 In essence, this makes it impossible to implement an HTTP resource 285 that conforms to both specifications. Due to the differing use cases 286 of XCAP and CalDAV, this may not be a problem in practice, but the 287 disagreement in itself is scary. Publication of these specifications 288 on the standards track will make it much harder for future protocols 289 to deal with this topic in a meaningful way (comments were sent 290 during IETF Last Call for CalDAV, see 291 ). 293 Note that of the two specifications above, [XCAP] profiles [RFC2616] 294 in that it makes a previously optional behavior required, while 295 [CALDAV] explicitly forbids a behavior which was previously allowed. 297 2. Notational Conventions 299 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL-NOT", 300 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 301 document are to be interpreted as described in [RFC2119]. 303 The terminology used here follows and extends that in the HTTP 304 specification [RFC2616], notably the augmented Backus-Naur Form (BNF) 305 defined in Section 2.1 of that document. 307 3. Clarifications on the Behavior of the 'ETag' Response Header 309 This section describes a minimal change to [RFC2616], proposed in . 312 At the end of Section 10.2 of [RFC2616], add: 314 The response MAY contain an ETag response header field indicating 315 the current value of the entity tag (Section 14.19) for the 316 requested variant. The value SHOULD be the same as the one 317 returned upon a subsequent HEAD request addressing the same 318 variant. 320 In Section 10.2.1 of [RFC2616], remove: 322 A 201 response MAY contain an ETag response header field 323 indicating the current value of the entity tag for the requested 324 variant just created, see Section 14.19. 326 In essence, this moves the statement about entity tags in write 327 operations from the specific case of status 201 Created into the more 328 generic description of the 2xx series status codes. 330 [[rcf2616.enhancements: Suggest other enhancements, such as actually 331 recommending returning updated entity tags in all write operations? 332 Also, should "requested variant" be clarified in the context of write 333 operations? --julian.reschke@greenbytes.de]] 335 4. The 'Entity-Transform' Response Header 337 The "Entity-Transform" response header can be used by the origin 338 server in responses to any request that affects the entity body of a 339 resource. It specifies in which way the server has modified the 340 entity before storage, thus allowing the user agent to decide about 341 whether it needs to refresh a local copy. 343 Entity-Transform = "Entity-Transform" ":" 1#transform-info 344 transform-info = "identity" | "unspecified" | token | coded-URI 345 coded-URI = "<" absolute-URI ">" 346 ; token: [RFC2616], Section 2.2 347 ; absolute-URI: [RFC3986], Section 4.3 349 A transform-info of "identity" specifies that the origin server has 350 stored the entity octet-by-octet, thus the user agent MAY use a local 351 copy for subsequent requests that rely on octet-by-octet identity 352 (such as a PUT with "Range" request header). Servers MUST NOT return 353 "identity" with any other transform-info values. 355 Both the absence of this response header and any value other than 356 "identity" specify that the origin server may have transformed the 357 entity before storage, thus a subsequent retrieval will not 358 necessarily return an exact copy of the stored entity. 360 Future IETF specifications may define other token values for more 361 precise information about how the content was rewritten. Values 362 taking the form of a coded-URI can be defined without registration; 363 in this case, it is RECOMMENDED to choose a URI that allows retrieval 364 of a human-readable description. 366 See [RFC2616], Section 6.2 for a definition of "response header". 368 4.1. Examples 370 Content was stored octet-by-octet: 372 Entity-Transform: identity 374 Content was transformed, but server doesn't specify how: 376 Entity-Transform: unspecified 377 Content was transformed, and server specifies the kind of 378 transformation: 380 Entity-Transform: 382 5. How This Helps 384 The clarification of [RFC2616] (see Section 3) makes it clear that 385 user agents can use "ETag" headers obtained in write operations, as 386 long as they do not require octet-by-octet identity. In particular, 387 a new entity tag can be returned for any method, such as a WebDAV 388 PROPPATCH (see [RFC2518], Section 8.2. This helps dealing with the 389 problem described in Appendix A.2. See Appendix A.3 for details. 391 The addition of the "Entity-Transform" response header (see 392 Section 4) enables origin servers to signal that they stored an exact 393 copy of the content, thus allowing clients not to refetch the 394 content. Note that by default (in absence of the response header), a 395 client can not make any assumptions about the server's behavior in 396 this regard. Thus clients will only benefit from new servers 397 explicitly setting the new header. 399 6. IANA Considerations 401 This document specifies the new HTTP response header listed below. 403 Header field name: Entity-Transform 405 Applicable protocol: http 407 Status: informational 409 Author/Change controller: IETF 411 Specification document: Section 4 of this specification 413 7. Security Considerations 415 This specification introduces no new security considerations beyond 416 those discussed in Section 15 of [RFC2616]. 418 8. References 419 8.1. Normative References 421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 422 Requirement Levels", BCP 14, RFC 2119, March 1997. 424 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 425 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 426 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 428 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 429 Resource Identifier (URI): Generic Syntax", STD 66, 430 RFC 3986, January 2005. 432 8.2. Informative References 434 [APP] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom 435 Publishing Protocol", draft-ietf-atompub-protocol-09 (work 436 in progress), June 2006. 438 [CALDAV] Daboo, C., Desruisseaux, B., and L. Dusseault, 439 "Calendaring Extensions to WebDAV (CalDAV)", 440 draft-dusseault-caldav-13 (work in progress), July 2006. 442 [HTML] Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 443 Specification", W3C REC-html401-19991224, December 1999, 444 . 446 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. 447 Jensen, "HTTP Extensions for Distributed Authoring -- 448 WEBDAV", RFC 2518, February 1999. 450 [XCAP] Rosenberg, J., "The Extensible Markup Language (XML) 451 Configuration Access Protocol (XCAP)", 452 draft-ietf-simple-xcap-11 (work in progress), May 2006. 454 [draft-whitehead-http-etag] 455 Whitehead, J., "Design Considerations for State 456 Identifiers in HTTP and WebDAV", 457 draft-whitehead-http-etag-00 (work in progress), 458 February 2006. 460 URIs 462 [1] 464 [2] 466 Appendix A. Use Cases 468 A.1. Simple Authoring 470 Let us consider a server not having the quality of preserving octet- 471 by-octet identity, for instance because of SVN-style keyword 472 expansion in text content (). 475 In this case, the client has previously retrieved the representation 476 for , and the server has returned the ETag 477 "1": 479 >> Request (1) 481 GET /test HTTP/1.1 482 Host: example.com 484 >> Response (1) 486 HTTP/1.1 200 OK 487 Content-Type: text/plain 488 ETag: "1" 490 # $Revision: 1 $ 491 Sample text. 493 The client now wants to update the resource. To avoid overwriting 494 somebody else's changes, it submits the PUT request with the HTTP 495 "If-Match" request header (see [RFC2616], Section 14.24): 497 >> Request (2) 499 PUT /test HTTP/1.1 500 Host: example.com 501 If-Match: "1" 503 # $Revision: 1 $ 504 New sample text. 506 If the resource was modified in the meantime, the server will reject 507 the request with a 412 Precondition Failed status: 509 >> Response (2a) 511 HTTP/1.1 412 Precondition Failed 512 Content-Type: text/plain 514 Precondition Failed: entity tag supplied in If-Match request header 515 did not match current. 517 In this case, the client usually has take care of merging the changes 518 made locally with those made on the server ("Merge Conflict"). 520 If there was no overlapping update, the server will execute the 521 request and return a new entity tag: 523 >> Response (2b) 525 HTTP/1.1 200 OK 526 Content-Type: text/plain 527 ETag: "2" 529 Note however, that at this point the client knows the new entity tag, 530 but doesn not know the current representation, which will have been 531 updated by the server to: 533 # $Revision: 2 $ 534 New sample text. 536 What seems to be a problem at first may not be a real problem in 537 practice. Let us assume that the client continues editing the 538 resource, using the entity tag obtained from the previous request, 539 but editing the entity it last sent: 541 >> Request (3) 543 PUT /test HTTP/1.1 544 Host: example.com 545 If-Match: "2" 547 # $Revision: 1 $ 548 A third attempt. 550 Assuming there was no overlapping update, the PUT request will 551 succeed: 553 >> Response (3) 555 HTTP/1.1 200 OK 556 Content-Type: text/plain 557 ETag: "3" 559 Note that the only problem here is that the client doesn't have an 560 exact copy of the entity it's editing. However, from the server's 561 point of view this is entirely irrelevant, because the "Revision" 562 keyword will be automatically updated upon every write anyway. 564 In any case, the final contents will be: 566 # $Revision: 3 $ 567 A third attempt. 569 A.2. Setting both Content and Metadata 571 In this example, the server exposes data extracted from the HTML 572 element ([HTML], Section 7.4.2) as a custom WebDAV property 573 ([RFC2518], Section 4), allowing both read and write access. 575 In the first step, the client obtains the current representation for 576 <http://example.com/test.html>: 578 >> Request (1) 580 GET /test.html HTTP/1.1 581 Host: example.com 583 >> Response (1) 585 HTTP/1.1 200 OK 586 Content-Type: text/html 587 ETag: "A" 589 <html> 590 <head> 591 </head> 592 <body> 593 </body> 594 </html> 596 Next, it adds one paragraph to the <body> element, and gets back a 597 new entity tag: 599 >> Request (2) 601 PUT /test.html HTTP/1.1 602 Host: example.com 603 If-Match: "A" 605 <html> 606 <head> 607 </head> 608 <body> 609 <p>First paragraph.</p> 610 </body> 611 </html> 613 >> Response (2) 615 HTTP/1.1 200 OK 616 ETag: "B" 618 Next, the client sets a custom "title" property (see [RFC2518], 619 Section 8.2): 621 >> Request (3) 623 PROPPATCH /test.html HTTP/1.1 624 Host: example.com 625 Content-Type: application/xml 627 <proppatch xmlns="DAV:"> 628 <set> 629 <prop> 630 <title xmlns="http://ns.example.org/"> 631 A sample document 632 633 634 635 636 >> Response (3) 638 HTTP/1.1 207 Multi-Status 639 Content-Type: application/xml 641 642 643 /test.html 644 645 646 647 </prop> 648 <status>HTTP/1.1 2OO OK</status> 649 </propstat> 650 </response> 651 </multistatus> 653 The server knows how to propagate property changes into the HTML 654 content, so it updates the entity by adding an HTML title document 655 accordingly. This causes the entity tag changing to "C". 657 The new entity body is shown below, but the client does not realize 658 that it did change at all. 660 <html> 661 <head> 662 <title>A sample document 663 664 665

First paragraph.

666 667 669 A subsequent attempt by the client to update the entity body will 670 fail, unless it realizes that changing WebDAV properties may affect 671 the entity as well. In this case, it would have had to get the 672 current entity tag before proceeding. Of course, this introduces an 673 additional round-trip, and a timing window during which overlapping 674 updates by other clients would go unnoticed. 676 A.3. Setting both Content and Metadata, new style 678 Below we repeat the example from above (Appendix A.2), but here the 679 origin server returns entity tags for all write operations, and the 680 user agent knows how to deal with them. That is, both take advantage 681 of [RFC2616] already allows. 683 >> Request (3) 685 PROPPATCH /test.html HTTP/1.1 686 Host: example.com 687 Content-Type: application/xml 689 690 691 692 693 A sample document 694 695 696 697 699 >> Response (3) 701 HTTP/1.1 207 Multi-Status 702 Content-Type: application/xml 703 ETag: "C" 705 706 707 /test.html 708 709 710 711 </prop> 712 <status>HTTP/1.1 2OO OK</status> 713 </propstat> 714 </response> 715 </multistatus> 717 As before, this causes the entity to change, and a new entity tag to 718 be assigned. But in this case, the origin server actually notifies 719 the client of the changed state by including the "ETag" response 720 header. 722 The client now will be aware that the requested entity change, and 723 can use the new entity tag in subsequent requests (potentially after 724 refreshing the local copy). 726 Author's Address 728 Julian F. Reschke 729 greenbytes GmbH 730 Hafenweg 16 731 Muenster, NW 48155 732 Germany 734 Phone: +49 251 2807760 735 Fax: +49 251 2807761 736 Email: julian.reschke@greenbytes.de 737 URI: http://greenbytes.de/tech/webdav/ 739 Full Copyright Statement 741 Copyright (C) The Internet Society (2006). 743 This document is subject to the rights, licenses and restrictions 744 contained in BCP 78, and except as set forth therein, the authors 745 retain all their rights. 747 This document and the information contained herein are provided on an 748 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 749 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 750 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 751 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 752 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 753 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 755 Intellectual Property 757 The IETF takes no position regarding the validity or scope of any 758 Intellectual Property Rights or other rights that might be claimed to 759 pertain to the implementation or use of the technology described in 760 this document or the extent to which any license under such rights 761 might or might not be available; nor does it represent that it has 762 made any independent effort to identify any such rights. Information 763 on the procedures with respect to rights in RFC documents can be 764 found in BCP 78 and BCP 79. 766 Copies of IPR disclosures made to the IETF Secretariat and any 767 assurances of licenses to be made available, or the result of an 768 attempt made to obtain a general license or permission for the use of 769 such proprietary rights by implementers or users of this 770 specification can be obtained from the IETF on-line IPR repository at 771 http://www.ietf.org/ipr. 773 The IETF invites any interested party to bring to its attention any 774 copyrights, patents or patent applications, or other proprietary 775 rights that may cover technology that may be required to implement 776 this standard. Please address the information to the IETF at 777 ietf-ipr@ietf.org. 779 Acknowledgment 781 Funding for the RFC Editor function is provided by the IETF 782 Administrative Support Activity (IASA).