idnits 2.17.1 draft-murchison-webdav-prefer-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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], [3], [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 RFC7240, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC7240, updated by this document, for RFC5378 checks: 2007-09-18) -- 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 14, 2016) is 2752 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 484 -- Looks like a reference, but probably isn't: '2' on line 486 -- Looks like a reference, but probably isn't: '3' on line 488 -- Looks like a reference, but probably isn't: '4' on line 490 -- Looks like a reference, but probably isn't: '5' on line 492 -- Looks like a reference, but probably isn't: '6' on line 494 -- Looks like a reference, but probably isn't: '7' on line 496 -- Looks like a reference, but probably isn't: '8' on line 498 -- Looks like a reference, but probably isn't: '9' on line 500 -- Looks like a reference, but probably isn't: '10' on line 502 -- Looks like a reference, but probably isn't: '11' on line 504 -- Looks like a reference, but probably isn't: '12' on line 506 -- Looks like a reference, but probably isn't: '13' on line 508 -- Looks like a reference, but probably isn't: '14' on line 510 -- Looks like a reference, but probably isn't: '15' on line 352 -- Looks like a reference, but probably isn't: '16' on line 356 -- Looks like a reference, but probably isn't: '17' on line 363 ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 20 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent Submission K. Murchison 3 Internet-Draft CMU 4 Updates: 7240 (if approved) October 14, 2016 5 Intended status: Standards Track 6 Expires: April 17, 2017 8 Use of the Prefer Header Field in Web Distributed Authoring and 9 Versioning (WebDAV) 10 draft-murchison-webdav-prefer-09 12 Abstract 14 This specification defines how the HTTP Prefer header field can be 15 used by a WebDAV client to request that certain behaviors be employed 16 by a server while constructing a response to a request. 18 Editorial Note (To be removed by RFC Editor before publication) 20 Please send comments to the Web Distributed Authoring and Versioning 21 (WebDAV) mailing list at [1], which may 22 be joined by sending a message with subject "subscribe" to 23 [2]. This mailing list is 24 archived at [3]. 26 Open Issues 28 o Does this draft also update the RFCs for CalDAV, CardDAV, and 29 those documenting the effected HTTP methods? 31 o Should we explitcly mention that this draft applies to any/all 32 *DAV protocols (e.g. CalDAV and CardDAV)? Would a title change 33 be in order? 35 o Should we use a non-protocol-specific REPORT example such as 36 DAV:sync-collection rather than using CalDAV:calendar-multiget? 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on April 17, 2017. 55 Copyright Notice 57 Copyright (c) 2016 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 74 2. Reducing WebDAV Response Verbosity with 75 "return=minimal" . . . . . . . . . . . . . . . . . . . . . . 3 76 2.1. Minimal PROPFIND Response . . . . . . . . . . . . . . . . 4 77 2.2. Minimal REPORT Response . . . . . . . . . . . . . . . . . 4 78 2.3. Minimal PROPPATCH Response . . . . . . . . . . . . . . . 4 79 2.4. Minimal MKCALENDAR / MKCOL Response . . . . . . . . . . . 5 80 3. Reducing WebDAV Round-Trips with 81 "return=representation" . . . . . . . . . . . . . . . . . . . 5 82 4. The "depth-noroot" Processing Preference . . . . . . . . . . 6 83 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 6 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 85 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 86 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 87 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 88 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 89 9.2. Informative References . . . . . . . . . . . . . . . . . 10 90 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11 91 Appendix A. The Brief and Extended Depth Request Header Fields . 11 92 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 12 93 B.1. PROPFIND . . . . . . . . . . . . . . . . . . . . . . . . 12 94 B.2. REPORT . . . . . . . . . . . . . . . . . . . . . . . . . 16 95 B.3. PROPPATCH . . . . . . . . . . . . . . . . . . . . . . . . 20 96 B.4. MKCOL . . . . . . . . . . . . . . . . . . . . . . . . . . 22 97 B.5. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 24 98 B.6. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 99 Appendix C. Change Log (To be removed by RFC Editor before 100 publication) . . . . . . . . . . . . . . . . . . . . 30 101 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33 103 1. Introduction 105 [RFC7240] defines the HTTP Prefer request header field and the 106 "return=minimal" preference which indicates that a client wishes for 107 the server to return a minimal response to a successful request, but 108 states that what constitutes an appropriate minimal response is left 109 solely to the discretion of the server. Section 2 of this 110 specification defines precisely what is expected of a server when 111 constructing minimal responses to successful WebDAV [RFC4918] 112 requests. 114 [RFC7240] also defines the "return=representaion" preference which 115 indicates that a client wishes for the server to include an entity 116 representing the current state of the resource in the response to a 117 successful request. Section 3 of this specification makes 118 recommendations on when this preference should be used by clients and 119 extends its applicability to 412 (Precondition Failed) [RFC7231] 120 responses. 122 Finally, Section 4 of this specifcation defines the "depth-noroot" 123 preference that can be used with WebDAV methods that support the 124 "Depth" header field.. 126 1.1. Notational Conventions 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in [RFC2119]. 132 This document references XML element types in the "DAV:" [RFC4918] 133 namespace outside of the context of an XML fragment. When doing so, 134 the string "DAV:" will be prepended to the XML element type. 136 2. Reducing WebDAV Response Verbosity with "return=minimal" 138 Some payload bodies in responses to WebDAV requests, such as 207 139 (Multi-Status) [RFC4918] responses, can be quite verbose or even 140 unnecessary at times. This specification defines how the Prefer 141 request header field, in conjunction with its "return=minimal" 142 preference, can be used by clients to reduce the verbosity of such 143 responses by requesting that the server omit those portions of the 144 response that can be inferred by their absence. 146 2.1. Minimal PROPFIND Response 148 When a PROPFIND [RFC4918] request contains a Prefer header field with 149 a preference of "return=minimal", the server SHOULD omit all 150 DAV:propstat XML elements containing a DAV:status XML element of 151 value 404 (Not Found) [RFC7231] from the 207 (Multi-Status) response. 152 If the omission of such a DAV:propstat element would result in a 153 DAV:response XML element containing zero DAV:propstat elements, the 154 server MUST substitute one of the following in its place: 156 o a DAV:propstat element consisting of an empty DAV:prop element and 157 a DAV:status element of value 200 (OK) [RFC7231] 159 o a DAV:status element of value 200 (OK) 161 See Appendix B.1 for examples. 163 2.2. Minimal REPORT Response 165 When a REPORT [RFC3253] request, whose report type results in a 207 166 (Multi-Status) response, contains a Prefer header field with a 167 preference of "return=minimal", the server SHOULD omit all 168 DAV:propstat XML elements containing a DAV:status XML element of 169 value 404 (Not Found) [RFC7231] from the 207 (Multi-Status) response. 170 If the omission of such a DAV:propstat element would result in a 171 DAV:response XML element containing zero DAV:propstat elements, the 172 server MUST substitute one of the following in its place: 174 o a DAV:propstat element consisting of an empty DAV:prop element and 175 a DAV:status element of value 200 (OK) [RFC7231] 177 o a DAV:status element of value 200 (OK) 179 See Appendix B.2 for examples. 181 2.3. Minimal PROPPATCH Response 183 When a PROPPATCH [RFC4918] request contains a Prefer header field 184 with a preference of "return=minimal", and all instructions are 185 processed successfully, the server SHOULD return one of the following 186 responses rather than a 207 (Multi-Status) response: 188 o 204 (No Content) [RFC7231] 190 o 200 (OK) [RFC7231] (preferably with a zero-length message body) 191 See Appendix B.3 for examples. 193 2.4. Minimal MKCALENDAR / MKCOL Response 195 Both the MKCALENDAR [RFC4791] and Extended MKCOL [RFC5689] 196 specifications indicate that a server MAY return a message body in 197 response to a successful request. This specification explicitly 198 defines the intended behavior in the presence of the Prefer header 199 field. 201 When a MKCALENDAR or an Extended MKCOL request contains a Prefer 202 header field with a preference of "return=minimal", and the 203 collection is created with all requested properties being set 204 successfully, the server SHOULD return a 201 (Created) [RFC7231] 205 response with an empty (zero-length) message body. 207 Note that the rationale for requiring that a minimal success response 208 have an empty body is twofold: 210 o [RFC4791] Section 5.3.1 states: "If a response body for a 211 successful request is included, it MUST be a CALDAV:mkcalendar- 212 response XML element." 214 o [RFC5689] Section 3 states: "When an empty response body is 215 returned with a success request status code, the client can assume 216 that all properties were set." 218 See Appendix B.4 for examples. 220 3. Reducing WebDAV Round-Trips with "return=representation" 222 The PUT, COPY, MOVE, [RFC4918] PATCH, [RFC5789] and POST [RFC5995] 223 methods can be used to create or update a resource. In some 224 instances, such as with CalDAV Scheduling [RFC6638], the created or 225 updated resource representation may differ from the representation 226 sent in the body of the request or referenced by the effective 227 request URI. In cases where the client would normally issue a 228 subsequent GET request to retrieve the current representation of the 229 resource, the client SHOULD instead include a Prefer header field 230 with the "return=representation" preference in the PUT, COPY, MOVE, 231 PATCH, or POST request. By doing this, the client can coalesce the 232 create/update and retrieve operations into one round-trip rather than 233 two. An additional benefit of using "return=representation" in such 234 a request is that the client will know that any changes to the 235 resource were produced by the server rather than a concurrent client, 236 thus providing a level of atomicity to the operation. 238 Frequently, clients using a state-changing method such as those 239 listed above will make them conditional by including either an If- 240 Match or If-None-Match [RFC7232] header field in the request. If the 241 specified condition evaluates to false, and the request includes a 242 Prefer header field with the "return=representation" preference, the 243 server SHOULD include an entity representing the current state of the 244 resource in the resulting 412 (Precondition Failed) [RFC7231] 245 response. 247 See Appendix B.5 and Appendix B.6 for examples. 249 4. The "depth-noroot" Processing Preference 251 The "depth-noroot" preference indicates that the client wishes for 252 the server to exclude the target (root) resource from processing by 253 the WebDAV method and only apply the WebDAV method to the target 254 resource's subordinate resources. 256 depth-noroot = "depth-noroot" 258 This preference is only intended to be used with WebDAV methods whose 259 definitions explicitly provide support for the Depth [RFC4918] header 260 field. Furthermore, this preference only applies when the Depth 261 header field has a value of "1" or "infinity" (either implicitly or 262 explicitly). 264 The "depth-noroot" preference MAY be used in conjunction with the 265 "return=minimal" preference in a single request. 267 See Appendix B.1 for examples. 269 5. Implementation Status 271 < RFC Editor: before publication please remove this section and the 272 reference to [RFC7942] > 274 This section records the status of known implementations of the 275 protocol defined by this specification at the time of posting of this 276 Internet-Draft, and is based on a proposal described in [RFC7942]. 277 The description of implementations in this section is intended to 278 assist the IETF in its decision processes in progressing drafts to 279 RFCs. Please note that the listing of any individual implementation 280 here does not imply endorsement by the IETF. Furthermore, no effort 281 has been spent to verify the information presented here that was 282 supplied by IETF contributors. This is not intended as, and must not 283 be construed to be, a catalog of available implementations or their 284 features. Readers are advised to note that other implementations may 285 exist. 287 According to [RFC7942], "this will allow reviewers and working groups 288 to assign due consideration to documents that have the benefit of 289 running code, which may serve as evidence of valuable experimentation 290 and feedback that have made the implemented protocols more mature. 291 It is up to the individual working groups to use this information as 292 they see fit". 294 5.1. Cyrus 296 The open source Cyrus [4] project is a highly scalable enterprise 297 mail system which also supports calendaring and contacts. This 298 production level CalDAV/CardDAV implementation supports all of the 299 preferences described in this document and successfully interoperates 300 with the CalDAVTester, Apple Calendar and Apple Contacts, and aCal 301 client implementations described below. This implementation is 302 freely distributable under a BSD style license from Computing 303 Services at Carnegie Mellon University [5]. 305 5.2. Calendar and Contacts Server 307 The open source Calendar and Contacts Server [6] project is a 308 standards-compliant server implementing the CalDAV and CardDAV 309 protocols. This production level implementation supports all of the 310 preferences described in this document and successfully interoperates 311 with the CalDAVTester and Apple Calendar and Apple Contacts client 312 implementations described below. This implementation is freely 313 distributable under the terms of the Apache License, Version 2.0 [7]. 315 5.3. Bedework 317 Bedework [8] is an open-source enterprise calendar system that 318 supports public, personal, and group calendaring. This production 319 level implementation supports the "return=minimal" preference 320 described in this document and successfully interoperates with the 321 CalDAVTester client implementation described below. This 322 implementation is freely distributable under the Jasig Licensing 323 Policy [9]. 325 5.4. DAViCal 327 DAViCal [10] is a server for calendar sharing using the CalDAV 328 protocol. This production level implementation supports the 329 "return=minimal" preference described in this document and 330 successfully interoperates with the CalDAVTester client 331 implementation described below. This implementation is Free Software 332 [11] distributable under the General Public License [12]. 334 5.5. Apple Calendar and Apple Contacts 336 The widely used Apple Calendar and Apple Contacts [13] clients are 337 standards-compliant clients implementing the CalDAV and CardDAV 338 protocols respectively. These production level implementations 339 support the "return=minimal" preference described in this document 340 and successfully interoperate with the Cyrus and 341 Calendar and Contacts Server implementations described above. These 342 client implementations are proprietary and are distributed as part of 343 Apple's desktop operating systems. 345 5.6. aCal 347 aCal [14] is an open source calendar client for Android which uses 348 the CalDAV standard for communication. This implementation makes 349 some use of each of the preferences described in this document and 350 successfully interoperates with the Cyrus server implementation 351 described above. This implementation is freely distributable under 352 the General Public License [15]. 354 5.7. CalDAVTester 356 CalDAVTester [16] is an open source test and performance application 357 designed to work with CalDAV and/or CardDAV servers and tests various 358 aspects of their protocol handling as well as performance. This 359 widely used implementation supports all of the preferences described 360 in this document and successfully interoperates with the server 361 implementations described above. This implementation is freely 362 distributable under the terms of the Apache License, Version 2.0 363 [17]. 365 6. Security Considerations 367 No new security considerations are introduced by use of the Prefer 368 header field with WebDAV request methods, beyond those discussed in 369 [RFC7240] and those already inherent in those methods. 371 7. IANA Considerations 373 The following preference is to be added to the Preferences Registry 374 defined in [RFC7240]. 376 o Preference: depth-noroot 378 o Description: The "depth-noroot" preference indicates that the 379 client wishes for the server to exclude the target (root) resource 380 from processing by the WebDAV method and only apply the WebDAV 381 method to the target resource's subordinate resources. 383 o Reference: Section 4 385 o Notes: This preference is only intended to be used with WebDAV 386 methods whose definitions explicitly provide support for the 387 "Depth" [RFC4918] header field. Furthermore, this preference only 388 applies when the "Depth" header field has a value of "1" or 389 "infinity" (either implicitly or explicitly). 391 8. Acknowledgements 393 The author would like to thank the following individuals for 394 contributing their ideas and support for writing this specification: 395 Cyrus Daboo, Helge Hess, Andrew McMillan, Arnaud Quillaud, and Julian 396 Reschke. 398 The author would also like to thank the Calendaring and Scheduling 399 Consortium for advice with this specification, and for organizing 400 interoperability testing events to help refine it. 402 9. References 404 9.1. Normative References 406 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 407 Requirement Levels", BCP 14, RFC 2119, 408 DOI 10.17487/RFC2119, March 1997, 409 . 411 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 412 Whitehead, "Versioning Extensions to WebDAV (Web 413 Distributed Authoring and Versioning)", RFC 3253, 414 DOI 10.17487/RFC3253, March 2002, 415 . 417 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 418 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 419 DOI 10.17487/RFC4791, March 2007, 420 . 422 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 423 Authoring and Versioning (WebDAV)", RFC 4918, 424 DOI 10.17487/RFC4918, June 2007, 425 . 427 [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring 428 and Versioning (WebDAV)", RFC 5689, DOI 10.17487/RFC5689, 429 September 2009, . 431 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 432 RFC 5789, DOI 10.17487/RFC5789, March 2010, 433 . 435 [RFC5995] Reschke, J., "Using POST to Add Members to Web Distributed 436 Authoring and Versioning (WebDAV) Collections", RFC 5995, 437 DOI 10.17487/RFC5995, September 2010, 438 . 440 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 441 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 442 DOI 10.17487/RFC7231, June 2014, 443 . 445 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 446 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 447 DOI 10.17487/RFC7232, June 2014, 448 . 450 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 451 DOI 10.17487/RFC7240, June 2014, 452 . 454 9.2. Informative References 456 [MSDN.aa493854] 457 Microsoft Developer Network, "PROPPATCH Method", June 458 2006, 459 . 461 [MSDN.aa563501] 462 Microsoft Developer Network, "Brief Header", June 2006, 463 . 465 [MSDN.aa563950] 466 Microsoft Developer Network, "Depth Header", June 2006, 467 . 469 [MSDN.aa580336] 470 Microsoft Developer Network, "PROPFIND Method", June 2006, 471 . 473 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 474 CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, 475 . 477 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 478 Code: The Implementation Status Section", BCP 205, 479 RFC 7942, DOI 10.17487/RFC7942, July 2016, 480 . 482 9.3. URIs 484 [1] http://www.cyrusimap.org/ 486 [2] http://www.cmu.edu/computing/ 488 [3] http://calendarserver.org/ 490 [4] http://www.apache.org/licenses/LICENSE-2.0.html 492 [5] http://www.bedework.org/ 494 [6] http://www.jasig.org/licensing 496 [7] http://www.davical.org/ 498 [8] http://www.gnu.org/philosophy/open-source-misses-the-point.html 500 [9] http://www.gnu.org/licenses/gpl.html 502 [10] http://www.apple.com/macos/ 504 [11] http://www.acal.me/ 506 [12] http://www.gnu.org/licenses/gpl.html 508 [13] http://calendarserver.org/wiki/CalDAVTester 510 [14] http://www.apache.org/licenses/LICENSE-2.0.html 512 Appendix A. The Brief and Extended Depth Request Header Fields 514 This document is based heavily on the Brief [MSDN.aa563501] and 515 extended Depth [MSDN.aa563950] request header fields. The behaviors 516 described in Section 2.1 and Section 2.3 are identical to those 517 provided by the Brief header field when used with the PROPFIND 518 [MSDN.aa580336] and PROPPATCH [MSDN.aa493854] methods respectively. 519 The behavior described in Section 4 is identical to that provided by 520 the "1,noroot" [MSDN.aa563950] and "infinity,noroot" [MSDN.aa563950] 521 Depth header field values. 523 Client and server implementations that already support the Brief 524 header field can add support for the "return=minimal" preference with 525 nominal effort. 527 If a server supporting the Prefer header field receives both the 528 Brief and Prefer header fields in a request, it MUST ignore the Brief 529 header field and only use the Prefer header field preferences. 531 Appendix B. Examples 533 B.1. PROPFIND 535 B.1.1. Typical PROPFIND request/response with Depth:1 537 This example tries to fetch one known and one unknown property from 538 child resources. 540 >> Request << 542 PROPFIND /container/ HTTP/1.1 543 Host: webdav.example.com 544 Content-Type: application/xml; charset=utf-8 545 Content-Length: xxxx 546 Depth: 1 548 549 550 551 552 553 554 556 >> Response << 558 HTTP/1.1 207 Multi-Status 559 Content-Type: application/xml; charset=utf-8 560 Content-Length: xxxx 562 563 564 565 /container/ 566 567 568 569 570 571 572 HTTP/1.1 200 OK 573 574 575 576 577 578 HTTP/1.1 404 Not Found 579 580 581 582 /container/work/ 583 584 585 586 587 588 589 HTTP/1.1 200 OK 590 591 592 593 594 595 HTTP/1.1 404 Not Found 596 597 598 599 /container/home/ 600 601 602 603 604 605 606 HTTP/1.1 200 OK 607 608 609 610 611 612 HTTP/1.1 404 Not Found 613 614 615 616 /container/foo.txt 617 618 619 620 621 HTTP/1.1 200 OK 622 623 624 625 626 627 HTTP/1.1 404 Not Found 628 629 630 632 B.1.2. Minimal PROPFIND request/response with Depth:1 634 This example tries to fetch one known and one unknown property from 635 child resources only. 637 >> Request << 639 PROPFIND /container/ HTTP/1.1 640 Host: webdav.example.com 641 Content-Type: application/xml; charset=utf-8 642 Content-Length: xxxx 643 Depth: 1 644 Prefer: return=minimal, depth-noroot 646 647 648 649 650 651 652 653 >> Response << 655 HTTP/1.1 207 Multi-Status 656 Content-Type: application/xml; charset=utf-8 657 Content-Length: xxxx 658 Preference-Applied: return=minimal, depth-noroot 660 661 662 663 /container/work/ 664 665 666 667 668 669 670 HTTP/1.1 200 OK 671 672 673 674 /container/home/ 675 676 677 678 679 680 681 HTTP/1.1 200 OK 682 683 684 685 /container/foo.txt 686 687 688 689 690 HTTP/1.1 200 OK 691 692 693 695 B.1.3. Minimal PROPFIND request/response with an empty DAV:propstat 696 element 698 This example tries to fetch an unknown property from a collection. 700 >> Request << 702 PROPFIND /container/ HTTP/1.1 703 Host: webdav.example.com 704 Content-Type: application/xml; charset=utf-8 705 Content-Length: xxxx 706 Prefer: return=minimal 708 709 710 711 712 713 715 >> Response << 717 HTTP/1.1 207 Multi-Status 718 Content-Type: application/xml; charset=utf-8 719 Content-Length: xxxx 720 Preference-Applied: return=minimal 722 723 724 725 /container/ 726 727 728 HTTP/1.1 200 OK 729 730 731 733 B.2. REPORT 734 B.2.1. Typical REPORT request/response 736 This example tries to fetch an unknown property from several 737 resources via the CALDAV:calendar-multiget [RFC4791] REPORT type. 739 >> Request << 741 REPORT /container/work/ HTTP/1.1 742 Host: caldav.example.com 743 Content-Type: application/xml; charset=utf-8 744 Content-Length: xxxx 746 747 750 751 752 753 754 /container/work/abc.ics 755 /container/work/qrs.ics 756 /container/work/xyz.ics 757 758 >> Response << 760 HTTP/1.1 207 Multi-Status 761 Content-Type: application/xml; charset=utf-8 762 Content-Length: xxxx 764 765 767 768 /container/work/abc.ics 769 770 771 "jahsd823ru" 772 773 HTTP/1.1 200 OK 774 775 776 777 778 779 HTTP/1.1 404 Not Found 780 781 782 783 /container/work/qrs.ics 784 HTTP/1.1 404 Not Found 785 786 787 /container/work/xyz.ics 788 789 790 "p08ulkj" 791 792 HTTP/1.1 200 OK 793 794 795 796 797 798 HTTP/1.1 404 Not Found 799 800 801 803 B.2.2. Minimal REPORT request/response 805 This example tries to fetch an unknown property from several 806 resources via the CALDAV:calendar-multiget [RFC4791] REPORT type. 808 >> Request << 810 REPORT /container/work/ HTTP/1.1 811 Host: caldav.example.com 812 Content-Type: application/xml; charset=utf-8 813 Content-Length: xxxx 814 Prefer: return=minimal 816 817 820 821 822 823 824 /container/work/abc.ics 825 /container/work/qrs.ics 826 /container/work/xyz.ics 827 828 >> Response << 830 HTTP/1.1 207 Multi-Status 831 Content-Type: application/xml; charset=utf-8 832 Content-Length: xxxx 833 Preference-Applied: return=minimal 835 836 837 838 /container/work/abc.ics 839 840 841 "jahsd823ru" 842 843 HTTP/1.1 200 OK 844 845 846 847 /container/work/qrs.ics 848 HTTP/1.1 404 Not Found 849 850 851 /container/work/xyz.ics 852 853 854 "p08ulkj" 855 856 HTTP/1.1 200 OK 857 858 859 861 B.3. PROPPATCH 863 B.3.1. Typical PROPPATCH request/response 864 >> Request << 866 PROPPATCH /container/ HTTP/1.1 867 Host: webdav.example.com 868 Content-Type: application/xml; charset=utf-8 869 Content-Length: xxxx 871 872 873 874 875 My Container 876 877 878 880 >> Response << 882 HTTP/1.1 207 Multi-Status 883 Content-Type: application/xml; charset=utf-8 884 Content-Length: xxxx 886 887 888 889 /container/ 890 891 892 893 894 HTTP/1.1 200 OK 895 896 897 899 B.3.2. Minimal PROPPATCH request/response 900 >> Request << 902 PROPPATCH /container/ HTTP/1.1 903 Host: webdav.example.com 904 Content-Type: application/xml; charset=utf-8 905 Content-Length: xxxx 906 Prefer: return=minimal 908 909 910 911 912 My Container 913 914 915 917 >> Response << 919 HTTP/1.1 200 OK 920 Content-Length: 0 921 Preference-Applied: return=minimal 923 B.4. MKCOL 925 B.4.1. Verbose MKCOL request/response 926 >> Request << 928 MKCOL /container/ HTTP/1.1 929 Host: webdav.example.com 930 Content-Type: application/xml; charset=utf-8 931 Content-Length: xxxx 933 934 935 936 937 My Container 938 939 940 942 >> Response << 944 HTTP/1.1 201 Created 945 Cache-Control: no-cache 946 Content-Type: application/xml; charset=utf-8 947 Content-Length: xxxx 949 950 951 952 953 954 955 HTTP/1.1 200 OK 956 957 959 B.4.2. Minimal MKCOL request/response 960 >> Request << 962 MKCOL /container/ HTTP/1.1 963 Host: webdav.example.com 964 Content-Type: application/xml; charset=utf-8 965 Content-Length: xxxx 966 Prefer: return=minimal 968 969 970 971 972 My Container 973 974 975 977 >> Response << 979 HTTP/1.1 201 Created 980 Cache-Control: no-cache 981 Content-Length: 0 982 Preference-Applied: return=minimal 984 B.5. POST 986 B.5.1. Typical resource creation and retrieval via POST + GET 988 Note that this request is not conditional because by using the POST 989 [RFC5995] method the client lets the server choose the resource URI, 990 thereby guaranteeing that it will not modify an existing resource. 992 >> Request << 994 POST /container/work;add-member/ HTTP/1.1 995 Host: caldav.example.com 996 Content-Type: text/calendar; charset=utf-8 997 Content-Length: xxxx 999 BEGIN:VCALENDAR 1000 VERSION:2.0 1001 PRODID:-//Example Corp.//CalDAV Client//EN 1002 BEGIN:VEVENT 1003 UID:CD87465FA 1004 SEQUENCE:0 1005 DTSTAMP:20120602T185254Z 1006 DTSTART:20120602T160000Z 1007 DTEND:20120602T170000Z 1008 TRANSP:OPAQUE 1009 SUMMARY:Lunch 1010 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1011 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1012 mailto:murch@example.com 1013 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1014 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@ 1015 example.com 1016 END:VEVENT 1017 END:VCALENDAR 1019 >> Response << 1021 HTTP/1.1 201 Created 1022 Location: /container/work/abc.ics 1023 Content-Length: 0 1025 Note that the server did not include any validator header fields (e.g 1026 ETag) in the response, signaling that the created representation 1027 differs from the representation sent in the body of the request. The 1028 client has to send a separate GET request to retrieve the current 1029 representation: 1031 >> Request << 1033 GET /container/work/abc.ics HTTP/1.1 1034 Host: caldav.example.com 1036 >> Response << 1038 HTTP/1.1 200 OK 1039 Content-Type: text/calendar; charset=utf-8 1040 Content-Length: xxxx 1041 ETag: "nahduyejc" 1042 Schedule-Tag: "jfd84hgbcn" 1044 BEGIN:VCALENDAR 1045 VERSION:2.0 1046 PRODID:-//Example Corp.//CalDAV Server//EN 1047 BEGIN:VEVENT 1048 UID:CD87465FA 1049 SEQUENCE:0 1050 DTSTAMP:20120602T185300Z 1051 DTSTART:20120602T160000Z 1052 DTEND:20120602T170000Z 1053 TRANSP:OPAQUE 1054 SUMMARY:Lunch 1055 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1056 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1057 mailto:murch@example.com 1058 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1059 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS= 1060 1.2:mailto:jdoe@example.com 1061 END:VEVENT 1062 END:VCALENDAR 1064 B.5.2. Streamlined resource creation and retrieval via POST 1066 Note that this request is not conditional because by using the POST 1067 [RFC5995] method the client lets the server choose the resource URI, 1068 thereby guaranteeing that it will not modify an existing resource. 1070 >> Request << 1072 POST /container/work;add-member/ HTTP/1.1 1073 Host: caldav.example.com 1074 Content-Type: text/calendar; charset=utf-8 1075 Content-Length: xxxx 1076 Prefer: return=representation 1078 BEGIN:VCALENDAR 1079 VERSION:2.0 1080 PRODID:-//Example Corp.//CalDAV Client//EN 1081 BEGIN:VEVENT 1082 UID:CD87465FA 1083 SEQUENCE:0 1084 DTSTAMP:20120602T185254Z 1085 DTSTART:20120602T160000Z 1086 DTEND:20120602T170000Z 1087 TRANSP:OPAQUE 1088 SUMMARY:Lunch 1089 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1090 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1091 mailto:murch@example.com 1092 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1093 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@ 1094 example.com 1095 END:VEVENT 1096 END:VCALENDAR 1097 >> Response << 1099 HTTP/1.1 201 Created 1100 Location: /container/work/abc.ics 1101 Content-Type: text/calendar; charset=utf-8 1102 Content-Length: xxxx 1103 Content-Location: /container/work/abc.ics 1104 ETag: "nahduyejc" 1105 Schedule-Tag: "jfd84hgbcn" 1106 Preference-Applied: return=representation 1108 BEGIN:VCALENDAR 1109 VERSION:2.0 1110 PRODID:-//Example Corp.//CalDAV Server//EN 1111 BEGIN:VEVENT 1112 UID:CD87465FA 1113 SEQUENCE:0 1114 DTSTAMP:20120602T185300Z 1115 DTSTART:20120602T160000Z 1116 DTEND:20120602T170000Z 1117 TRANSP:OPAQUE 1118 SUMMARY:Lunch 1119 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1120 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1121 mailto:murch@example.com 1122 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1123 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS= 1124 1.2:mailto:jdoe@example.com 1125 END:VEVENT 1126 END:VCALENDAR 1128 B.6. PUT 1130 B.6.1. Typical conditional resource update failure and retrieval via 1131 PUT + GET 1133 >> Request << 1135 PUT /container/motd.txt HTTP/1.1 1136 Host: dav.example.com 1137 Content-Type: text/plain 1138 Content-Length: xxxx 1139 If-Match: "asd973" 1141 Either write something worth reading or do something worth writing. 1143 >> Response << 1145 HTTP/1.1 412 Precondition Failed 1146 Content-Length: 0 1148 The resource has been modified by another user agent (ETag mismatch), 1149 therefore the client has to send a separate GET request to retrieve 1150 the current representation: 1152 >> Request << 1154 GET /container/motd.txt HTTP/1.1 1155 Host: dav.example.com 1157 >> Response << 1159 HTTP/1.1 200 OK 1160 Content-Type: text/plain 1161 Content-Length: xxxx 1162 ETag: "789sdas" 1164 An investment in knowledge pays the best interest. 1166 B.6.2. Streamlined conditional resource update failure and retrieval 1167 via PUT 1169 >> Request << 1171 PUT /container/motd.txt HTTP/1.1 1172 Host: dav.example.com 1173 Content-Type: text/plain 1174 Content-Length: xxxx 1175 If-Match: "asd973" 1176 Prefer: return=representation 1178 Either write something worth reading or do something worth writing. 1180 >> Response << 1182 HTTP/1.1 412 Precondition Failed 1183 Content-Type: text/plain 1184 Content-Length: xxxx 1185 Content-Location: /container/motd.txt 1186 ETag: "789sdas" 1187 Preference-Applied: return=representation 1189 An investment in knowledge pays the best interest. 1191 Appendix C. Change Log (To be removed by RFC Editor before publication) 1193 C.1. Since -08 1195 o Moved examples to Appendix B. 1197 o Added reference to HTTP PATCH. 1199 o Updated Implementation Status reference from RFC 6982 to RFC 7942. 1201 C.2. Since -07 1203 o No substantive changes. Refreshed due to pending expiration. 1205 C.3. Since -06 1207 o Updated HTTPbis and Prefer references to published RFCs. 1209 C.4. Since -05 1211 o Allow a minimal PROPFIND/REPORT response to contain a DAV:status 1212 element rather than an empty DAV:propstat element. 1214 o Allow 204 (No Content) as a minimal PROPATCH success response. 1216 o Added justification for why a minimal MKCOL/MKCALENDAR success 1217 response must have an empty body. 1219 o Added text and an example of how "return=representation" can be 1220 employed with a conditional state-changing request and a 412 1221 (Precondition Failed) response. 1223 o Added a note to the POST+GET example bringing attention to the 1224 lack of a validator header field in the POST response. 1226 o Reduced the number of inline references. 1228 o Limited most examples to vanilla WebDAV. 1230 o Reduced number of items in TOC. 1232 o Removed the recommendation that the legacy Brief header 1233 functionality should be implemented. 1235 o Added note about how a server should handle a request that 1236 contains both Brief and Prefer. 1238 o Other editorial tweaks from Julian Reschke. 1240 C.5. Since -04 1242 o Added note stating where to send comments. 1244 C.6. Since -03 1246 o Limited "Updates" to just RFC 4918. 1248 o Consensus from CalConnect membership that a "depth-root" option is 1249 unnecessary at this point. 1251 o Consensus from CalConnect membership to remove Vary header field 1252 from PROPFIND and REPORT responses since these responses don't 1253 appear to be cached. 1255 o Updated "Implementation Status" section boilerplate to RFC 6982. 1257 o Added aCal to "Implementation Status" section. 1259 o Added note that servers SHOULD respond with Preference-Applied 1260 when return=minimal is used with PROPFIND or REPORT. 1262 C.7. Since -02 1264 o Reintroduced "Updates" to header. 1266 o Added text noting that "return=representation" provides a level of 1267 atomicity to the operation. 1269 o Added "Implementation Status" section. 1271 o Tweaked/corrected some examples.. 1273 o Updated HTTPbis references. 1275 C.8. Since -01 1277 o Removed "Updates" from header. 1279 o Fixed some missing/incorrect references. 1281 o Reintroduced Cache-Control:no-cache to MKCOL responses. 1283 C.9. Since -00 1285 o Updated to comply with draft-snell-httpprefer-18. 1287 o Reordered "Minimal REPORT Response" and "Minimal PROPPATCH 1288 Response" sections. 1290 o Added some explanatory text to examples. 1292 C.10. Since CalConnect XXIV 1294 o Updated references. 1296 o Stated that "depth-noroot" can be used in conjuction with 1297 "return=minimal". 1299 o Added text mentioning that "depth-noroot" is based on the MSDN 1300 "1,noroot" and "infinity,noroot" Depth header values. 1302 o The server behavior required when "return=minimal" would result in 1303 zero DAV:propstat elements has been changed 1305 from: 1307 1308 1309 1310 /container/ 1311 HTTP/1.1 200 OK 1312 1313 1315 to the slightly more verbose: 1317 1318 1319 1320 /container/ 1321 1322 1323 HTTP/1.1 200 OK 1324 1325 1326 1328 Author's Address 1330 Kenneth Murchison 1331 Carnegie Mellon University 1332 5000 Forbes Avenue 1333 Pittsburgh, PA 15213 1334 US 1336 Phone: +1 412 268 1982 1337 Email: murch@andrew.cmu.edu