idnits 2.17.1 draft-murchison-webdav-prefer-14.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], [RFC7240], [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 directly say this. It does mention RFC7240 though, so this could be OK. 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 (January 13, 2017) is 2653 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 563 -- Looks like a reference, but probably isn't: '2' on line 565 -- Looks like a reference, but probably isn't: '3' on line 567 -- Looks like a reference, but probably isn't: '4' on line 569 -- Looks like a reference, but probably isn't: '5' on line 571 -- Looks like a reference, but probably isn't: '6' on line 573 -- Looks like a reference, but probably isn't: '7' on line 575 -- Looks like a reference, but probably isn't: '8' on line 577 -- Looks like a reference, but probably isn't: '9' on line 579 -- Looks like a reference, but probably isn't: '10' on line 581 -- Looks like a reference, but probably isn't: '11' on line 583 -- Looks like a reference, but probably isn't: '12' on line 585 -- Looks like a reference, but probably isn't: '13' on line 587 -- Looks like a reference, but probably isn't: '14' on line 589 -- Looks like a reference, but probably isn't: '15' on line 384 -- Looks like a reference, but probably isn't: '16' on line 388 -- Looks like a reference, but probably isn't: '17' on line 395 ** 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 Network Working Group K. Murchison 3 Internet-Draft CMU 4 Updates: 7240 (if approved) January 13, 2017 5 Intended status: Standards Track 6 Expires: July 17, 2017 8 Use of the Prefer Header Field in Web Distributed Authoring and 9 Versioning (WebDAV) 10 draft-murchison-webdav-prefer-14 12 Abstract 14 This document defines an update to the HTTP Prefer header field 15 [RFC7240] to specify how it can be used by a WebDAV client to request 16 that certain behaviors be employed by a server while constructing a 17 response to a request. Furthermore, it defines the new "depth- 18 noroot" preference. 20 Editorial Note (To be removed by RFC Editor before publication) 22 Please send comments to the Web Distributed Authoring and Versioning 23 (WebDAV) mailing list at [1], which may 24 be joined by sending a message with subject "subscribe" to 25 [2]. This mailing list is 26 archived at [3]. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on July 17, 2017. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 64 2. Reducing WebDAV Response Verbosity with 65 "return=minimal" . . . . . . . . . . . . . . . . . . . . . . 3 66 2.1. Minimal PROPFIND and REPORT Responses . . . . . . . . . . 4 67 2.2. Minimal PROPPATCH Response . . . . . . . . . . . . . . . 4 68 2.3. Minimal MKCALENDAR and MKCOL Responses . . . . . . . . . 5 69 3. Reducing WebDAV Round-Trips with 70 "return=representation" . . . . . . . . . . . . . . . . . . . 5 71 3.1. Successful State-Changing Requests . . . . . . . . . . . 5 72 3.2. Unsuccessful Conditional State-Changing 73 Requests . . . . . . . . . . . . . . . . . . . . . . . . 6 74 4. The "depth-noroot" Processing Preference . . . . . . . . . . 7 75 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 7 76 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 77 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 7.1. Preference Registration . . . . . . . . . . . . . . . . . 9 79 7.2. Method References . . . . . . . . . . . . . . . . . . . . 10 80 7.3. Status Code References . . . . . . . . . . . . . . . . . 10 81 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 82 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 83 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 84 9.2. Informative References . . . . . . . . . . . . . . . . . 12 85 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 86 Appendix A. The Brief and Extended Depth Request Header Fields . 13 87 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 14 88 B.1. PROPFIND . . . . . . . . . . . . . . . . . . . . . . . . 14 89 B.2. REPORT . . . . . . . . . . . . . . . . . . . . . . . . . 18 90 B.3. PROPPATCH . . . . . . . . . . . . . . . . . . . . . . . . 23 91 B.4. MKCOL . . . . . . . . . . . . . . . . . . . . . . . . . . 25 92 B.5. POST . . . . . . . . . . . . . . . . . . . . . . . . . . 26 93 B.6. PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 94 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 32 95 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 36 97 1. Introduction 99 [RFC7240] defines the HTTP Prefer request header field and the 100 "return=minimal" preference which indicates that a client wishes for 101 the server to return a minimal response to a successful request, but 102 states that what constitutes an appropriate minimal response is left 103 solely to the discretion of the server. Section 2 of this 104 specification defines precisely what is expected of a server when 105 constructing minimal responses to successful WebDAV [RFC4918] 106 requests. 108 [RFC7240] also defines the "return=representation" preference which 109 indicates that a client wishes for the server to include an entity 110 representing the current state of the resource in the response to a 111 successful request. Section 3 of this specification makes 112 recommendations on when this preference should be used by clients and 113 extends its applicability to 412 (Precondition Failed) [RFC7232] 114 responses. 116 Finally, Section 4 of this specification defines the "depth-noroot" 117 preference that can be used with WebDAV methods that support the 118 "Depth" header field. 120 1.1. Notational Conventions 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 This document references XML element types in the "DAV:" [RFC4918], 127 "urn:ietf:params:xml:ns:caldav" [RFC4791], and 128 "urn:ietf:params:xml:ns:carddav" [RFC6352] namespaces outside of the 129 context of an XML fragment. When doing so, the strings "DAV:", 130 "CALDAV:", and "CARDDAV:" will be prepended to the XML element types 131 respectively. 133 2. Reducing WebDAV Response Verbosity with "return=minimal" 135 Some payload bodies in responses to WebDAV requests, such as 207 136 (Multi-Status) [RFC4918] responses, can be quite verbose or even 137 unnecessary at times. This specification defines how the Prefer 138 request header field, in conjunction with its "return=minimal" 139 preference, can be used by clients to reduce the verbosity of such 140 responses by requesting that the server omit those portions of the 141 response that can be inferred by their absence. 143 2.1. Minimal PROPFIND and REPORT Responses 145 When a PROPFIND [RFC4918] request, or a REPORT [RFC3253] request 146 whose report type results in a 207 (Multi-Status) response, contains 147 a Prefer header field with a preference of "return=minimal", the 148 server SHOULD omit all DAV:propstat XML elements containing a 149 DAV:status XML element of value 404 (Not Found) [RFC7231] from the 150 207 (Multi-Status) response. If the omission of such a DAV:propstat 151 element would result in a DAV:response XML element containing zero 152 DAV:propstat elements, the server MUST substitute one of the 153 following in its place: 155 o a DAV:propstat element consisting of an empty DAV:prop element and 156 a DAV:status element of value 200 (OK) [RFC7231] 158 o a DAV:status element of value 200 (OK) 160 The following report types are candidates that could benefit from use 161 of the "return=minimal" preference. NOTE: This list is not intended 162 to be normative or exhaustive. 164 o DAV:expand-property [RFC3253] 166 o DAV:acl-principal-prop-set [RFC3744] 168 o DAV:principal-property-search [RFC3744] 170 o DAV:sync-collection [RFC6578] 172 o CALDAV:calendar-query [RFC4791] 174 o CALDAV:calendar-multiget [RFC4791] 176 o CARDDAV:addressbook-query [RFC6352] 178 o CARDDAV:addressbook-multiget [RFC6352] 180 See Appendix B.1 and Appendix B.2 for examples. 182 2.2. Minimal PROPPATCH Response 184 When a PROPPATCH [RFC4918] request contains a Prefer header field 185 with a preference of "return=minimal", and all instructions are 186 processed successfully, the server SHOULD return one of the following 187 responses rather than a 207 (Multi-Status) response: 189 o 204 (No Content) [RFC7231] 191 o 200 (OK) [RFC7231] (preferably with a zero-length message body) 193 See Appendix B.3 for examples. 195 2.3. Minimal MKCALENDAR and MKCOL Responses 197 Both the MKCALENDAR [RFC4791] and Extended MKCOL [RFC5689] 198 specifications indicate that a server MAY return a message body in 199 response to a successful request. This specification explicitly 200 defines the intended behavior in the presence of the Prefer header 201 field. 203 When a MKCALENDAR or an Extended MKCOL request contains a Prefer 204 header field with a preference of "return=minimal", and the 205 collection is created with all requested properties being set 206 successfully, the server SHOULD return a 201 (Created) [RFC7231] 207 response with an empty (zero-length) message body. 209 Note that the rationale for requiring that a minimal success response 210 have an empty body is twofold: 212 o [RFC4791] Section 5.3.1 states: "If a response body for a 213 successful request is included, it MUST be a CALDAV:mkcalendar- 214 response XML element." 216 o [RFC5689] Section 3 states: "When an empty response body is 217 returned with a success request status code, the client can assume 218 that all properties were set." 220 See Appendix B.4 for examples. 222 3. Reducing WebDAV Round-Trips with "return=representation" 224 [RFC7240] describes the "return=representation" preference as being 225 intended to provide a means of optimizing communication between the 226 client and server by eliminating the need for a subsequent GET 227 request to retrieve the current representation of the resource 228 following a modification. This preference is equally applicable to 229 situations where the server itself modifies a resource, and where a 230 resource has been modified by another client. 232 3.1. Successful State-Changing Requests 234 The state-changing methods PUT [RFC7231], COPY/MOVE [RFC4918], PATCH 235 [RFC5789], and POST [RFC5995] can be used to create or update a 236 resource. In some instances, such as with CalDAV Scheduling 238 [RFC6638], the created or updated resource representation may differ 239 from the representation sent in the body of the request or referenced 240 by the effective request URI. In cases where the client, upon 241 receiving a 2xx (Successful) [RFC7231] response to its state-changing 242 request, would normally issue a subsequent GET request to retrieve 243 the current representation of the resource, the client can instead 244 include a Prefer header field with the "return=representation" 245 preference in the state-changing request. 247 When a state-changing request contains a Prefer header field with a 248 preference of "return=representation", and the resource is created or 249 updated successfully, the server SHOULD include an entity 250 representing the current state resource in the resulting 201 251 (Created) or 200 (OK) [RFC7231] response. In addition to coalescing 252 the create/update and retrieve operations into a single round-trip, 253 by returning the current representation of the resource in the 254 response the client will know that any changes to the resource were 255 produced by the server rather than a concurrent client, thus 256 providing a level of atomicity to the operation. 258 See Appendix B.5 for examples. 260 3.2. Unsuccessful Conditional State-Changing Requests 262 Frequently, clients using a state-changing method such as those 263 listed above will make them conditional by including either an If- 264 Match or If-None-Match [RFC7232] header field in the request. This 265 is done to prevent the client from accidentally overwriting a 266 resource whose current state has been modified by another client 267 acting in parallel. In cases where the client, upon receiving a 412 268 (Precondition Failed) [RFC7232] response to its conditional state- 269 changing request, would normally issue a subsequent GET request to 270 retrieve the current representation of the resource, the client can 271 instead include a Prefer header field with the 272 "return=representation" preference in the conditional state-changing 273 request. 275 When a conditional state-changing request contains a Prefer header 276 field with a preference of "return=representation", and the specified 277 condition evaluates to false, the server SHOULD include an entity 278 representing the current state of the resource in the resulting 412 279 (Precondition Failed) [RFC7232] response. 281 See Appendix B.6 for examples. 283 4. The "depth-noroot" Processing Preference 285 The "depth-noroot" preference indicates that the client wishes for 286 the server to exclude the target (root) resource from processing by 287 the WebDAV method and only apply the WebDAV method to the target 288 resource's subordinate resources. 290 This preference is only intended to be used with WebDAV methods whose 291 definitions explicitly provide support for the Depth [RFC4918] header 292 field. Furthermore, this preference only applies when the Depth 293 header field has a value of "1" or "infinity" (either implicitly or 294 explicitly). 296 The "depth-noroot" preference MAY be used in conjunction with the 297 "return=minimal" preference in a single request. 299 See Appendix B.1 for examples. 301 5. Implementation Status 303 < RFC Editor: before publication please remove this section, the 304 reference to [RFC7942], and section 9.3 ("URIs")> 306 This section records the status of known implementations of the 307 protocol defined by this specification at the time of posting of this 308 Internet-Draft, and is based on a proposal described in [RFC7942]. 309 The description of implementations in this section is intended to 310 assist the IETF in its decision processes in progressing drafts to 311 RFCs. Please note that the listing of any individual implementation 312 here does not imply endorsement by the IETF. Furthermore, no effort 313 has been spent to verify the information presented here that was 314 supplied by IETF contributors. This is not intended as, and must not 315 be construed to be, a catalog of available implementations or their 316 features. Readers are advised to note that other implementations may 317 exist. 319 According to [RFC7942], "this will allow reviewers and working groups 320 to assign due consideration to documents that have the benefit of 321 running code, which may serve as evidence of valuable experimentation 322 and feedback that have made the implemented protocols more mature. 323 It is up to the individual working groups to use this information as 324 they see fit". 326 5.1. Cyrus 328 The open source Cyrus [4] project is a highly scalable enterprise 329 mail system which also supports calendaring and contacts. This 330 production level CalDAV/CardDAV implementation supports all of the 331 preferences described in this document and successfully interoperates 332 with the CalDAVTester, Apple Calendar and Apple Contacts, and aCal 333 client implementations described below. This implementation is 334 freely distributable under a BSD style license from Computing 335 Services at Carnegie Mellon University [5]. 337 5.2. Calendar and Contacts Server 339 The open source Calendar and Contacts Server [6] project is a 340 standards-compliant server implementing the CalDAV and CardDAV 341 protocols. This production level implementation supports all of the 342 preferences described in this document and successfully interoperates 343 with the CalDAVTester and Apple Calendar and Apple Contacts client 344 implementations described below. This implementation is freely 345 distributable under the terms of the Apache License, Version 2.0 [7]. 347 5.3. Bedework 349 Bedework [8] is an open-source enterprise calendar system that 350 supports public, personal, and group calendaring. This production 351 level implementation supports the "return=minimal" preference 352 described in this document and successfully interoperates with the 353 CalDAVTester client implementation described below. This 354 implementation is freely distributable under the Jasig Licensing 355 Policy [9]. 357 5.4. DAViCal 359 DAViCal [10] is a server for calendar sharing using the CalDAV 360 protocol. This production level implementation supports the 361 "return=minimal" preference described in this document and 362 successfully interoperates with the CalDAVTester client 363 implementation described below. This implementation is Free Software 364 [11] distributable under the General Public License [12]. 366 5.5. Apple Calendar and Apple Contacts 368 The widely used Apple Calendar and Apple Contacts [13] clients are 369 standards-compliant clients implementing the CalDAV and CardDAV 370 protocols respectively. These production level implementations 371 support the "return=minimal" preference described in this document 372 and successfully interoperate with the Cyrus and 373 Calendar and Contacts Server implementations described above. These 374 client implementations are proprietary and are distributed as part of 375 Apple's desktop operating systems. 377 5.6. aCal 379 aCal [14] is an open source calendar client for Android which uses 380 the CalDAV standard for communication. This implementation makes 381 some use of each of the preferences described in this document and 382 successfully interoperates with the Cyrus server implementation 383 described above. This implementation is freely distributable under 384 the General Public License [15]. 386 5.7. CalDAVTester 388 CalDAVTester [16] is an open source test and performance application 389 designed to work with CalDAV and/or CardDAV servers and tests various 390 aspects of their protocol handling as well as performance. This 391 widely used implementation supports all of the preferences described 392 in this document and successfully interoperates with the server 393 implementations described above. This implementation is freely 394 distributable under the terms of the Apache License, Version 2.0 395 [17]. 397 6. Security Considerations 399 No new security considerations are introduced by use of the Prefer 400 header field with WebDAV request methods, beyond those discussed in 401 [RFC7240] and those already inherent in those methods. 403 7. IANA Considerations 405 7.1. Preference Registration 407 The following preference is to be added to the HTTP Preferences 408 Registry defined in Section 5.1 of [RFC7240]. 410 Preference: depth-noroot 412 Description: The "depth-noroot" preference indicates that the client 413 wishes for the server to exclude the target (root) resource from 414 processing by the WebDAV method and only apply the WebDAV method 415 to the target resource's subordinate resources. 417 Reference: RFCXXXX, Section 4 419 Notes: This preference is only intended to be used with WebDAV 420 methods whose definitions explicitly provide support for the 421 "Depth" [RFC4918] header field. Furthermore, this preference only 422 applies when the "Depth" header field has a value of "1" or 423 "infinity" (either implicitly or explicitly). 425 7.2. Method References 427 The following methods are to have their references updated in the 428 HTTP Method Registry (). 431 +------------+------------------------------------------------------+ 432 | Method | References | 433 | Name | | 434 +------------+------------------------------------------------------+ 435 | MKCALENDAR | RFC4791, Section 5.3.1; RFCXXXX, Section 2.3 | 436 | MKCOL | RFC4918, Section 9.3; RFC 5689, Section 3; RFCXXXX, | 437 | | Section 2.3 | 438 | PROPFIND | RFC4918, Section 9.1; RFCXXXX, Section 2.1 | 439 | PROPPATCH | RFC4918, Section 9.2; RFCXXXX, Section 2.2 | 440 | REPORT | RFC3253, Section 3.6; RFCXXXX, Section 2.1 | 441 +------------+------------------------------------------------------+ 443 7.3. Status Code References 445 The following status code is to have its references updated in the 446 HTTP Status Code Registry (). 449 +-------+--------------------------------------------+ 450 | Value | References | 451 +-------+--------------------------------------------+ 452 | 412 | RFC7232, Section 4.2; RFCXXXX, Section 3.2 | 453 +-------+--------------------------------------------+ 455 8. Acknowledgements 457 The author would like to thank the following individuals for 458 contributing their ideas and support for writing this specification: 459 Cyrus Daboo, Helge Hess, Andrew McMillan, Arnaud Quillaud, and Julian 460 Reschke. 462 The author would also like to thank the Calendaring and Scheduling 463 Consortium for advice with this specification, and for organizing 464 interoperability testing events to help refine it. 466 9. References 468 9.1. Normative References 470 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 471 Requirement Levels", BCP 14, RFC 2119, 472 DOI 10.17487/RFC2119, March 1997, 473 . 475 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. 476 Whitehead, "Versioning Extensions to WebDAV (Web 477 Distributed Authoring and Versioning)", RFC 3253, 478 DOI 10.17487/RFC3253, March 2002, 479 . 481 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 482 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 483 DOI 10.17487/RFC4791, March 2007, 484 . 486 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 487 Authoring and Versioning (WebDAV)", RFC 4918, 488 DOI 10.17487/RFC4918, June 2007, 489 . 491 [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring 492 and Versioning (WebDAV)", RFC 5689, DOI 10.17487/RFC5689, 493 September 2009, . 495 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 496 RFC 5789, DOI 10.17487/RFC5789, March 2010, 497 . 499 [RFC5995] Reschke, J., "Using POST to Add Members to Web Distributed 500 Authoring and Versioning (WebDAV) Collections", RFC 5995, 501 DOI 10.17487/RFC5995, September 2010, 502 . 504 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 505 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 506 DOI 10.17487/RFC7231, June 2014, 507 . 509 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 510 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 511 DOI 10.17487/RFC7232, June 2014, 512 . 514 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 515 DOI 10.17487/RFC7240, June 2014, 516 . 518 9.2. Informative References 520 [MSDN.aa493854] 521 Microsoft Developer Network, "PROPPATCH Method", June 522 2006, 523 . 525 [MSDN.aa563501] 526 Microsoft Developer Network, "Brief Header", June 2006, 527 . 529 [MSDN.aa563950] 530 Microsoft Developer Network, "Depth Header", June 2006, 531 . 533 [MSDN.aa580336] 534 Microsoft Developer Network, "PROPFIND Method", June 2006, 535 . 537 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web 538 Distributed Authoring and Versioning (WebDAV) Access 539 Control Protocol", RFC 3744, DOI 10.17487/RFC3744, May 540 2004, . 542 [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed 543 Authoring and Versioning (WebDAV)", RFC 6352, 544 DOI 10.17487/RFC6352, August 2011, 545 . 547 [RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for 548 Web Distributed Authoring and Versioning (WebDAV)", 549 RFC 6578, DOI 10.17487/RFC6578, March 2012, 550 . 552 [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to 553 CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, 554 . 556 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 557 Code: The Implementation Status Section", BCP 205, 558 RFC 7942, DOI 10.17487/RFC7942, July 2016, 559 . 561 9.3. URIs 563 [1] http://www.cyrusimap.org/ 565 [2] http://www.cmu.edu/computing/ 567 [3] http://calendarserver.org/ 569 [4] http://www.apache.org/licenses/LICENSE-2.0.html 571 [5] http://www.bedework.org/ 573 [6] http://www.jasig.org/licensing 575 [7] http://www.davical.org/ 577 [8] http://www.gnu.org/philosophy/open-source-misses-the-point.html 579 [9] http://www.gnu.org/licenses/gpl.html 581 [10] http://www.apple.com/macos/ 583 [11] http://www.acal.me/ 585 [12] http://www.gnu.org/licenses/gpl.html 587 [13] http://calendarserver.org/wiki/CalDAVTester 589 [14] http://www.apache.org/licenses/LICENSE-2.0.html 591 Appendix A. The Brief and Extended Depth Request Header Fields 593 This document is based heavily on the Brief [MSDN.aa563501] and 594 extended Depth [MSDN.aa563950] request header fields. The behaviors 595 described in Section 2.1 and Section 2.2 are identical to those 596 provided by the Brief header field when used with the PROPFIND 597 [MSDN.aa580336] and PROPPATCH [MSDN.aa493854] methods respectively. 598 The behavior described in Section 4 is identical to that provided by 599 the "1,noroot" [MSDN.aa563950] and "infinity,noroot" [MSDN.aa563950] 600 Depth header field values. 602 Client and server implementations that already support the Brief 603 header field can add support for the "return=minimal" preference with 604 nominal effort. 606 If a server supporting the Prefer header field receives both the 607 Brief and Prefer header fields in a request, clients can expect the 608 server to ignore the Brief header field and only use the Prefer 609 header field preferences. 611 Appendix B. Examples 613 B.1. PROPFIND 615 B.1.1. Typical PROPFIND request/response with Depth:1 617 This example tries to fetch one known and one unknown property from 618 child resources. 620 >> Request << 622 PROPFIND /container/ HTTP/1.1 623 Host: webdav.example.com 624 Content-Type: application/xml; charset=utf-8 625 Content-Length: xxxx 626 Depth: 1 628 629 630 631 632 633 634 636 >> Response << 638 HTTP/1.1 207 Multi-Status 639 Content-Type: application/xml; charset=utf-8 640 Content-Length: xxxx 642 643 645 646 /container/ 647 648 649 650 651 652 653 HTTP/1.1 200 OK 654 655 656 657 658 659 HTTP/1.1 404 Not Found 660 661 662 663 /container/work/ 664 665 666 667 668 669 670 HTTP/1.1 200 OK 671 672 673 674 675 676 HTTP/1.1 404 Not Found 677 678 679 680 /container/home/ 681 682 683 684 685 686 687 HTTP/1.1 200 OK 688 689 690 691 692 693 HTTP/1.1 404 Not Found 694 695 696 697 /container/foo.txt 698 699 700 701 702 HTTP/1.1 200 OK 703 704 705 706 708 709 HTTP/1.1 404 Not Found 710 711 712 714 B.1.2. Minimal PROPFIND request/response with Depth:1 716 This example tries to fetch one known and one unknown property from 717 child resources only. 719 >> Request << 721 PROPFIND /container/ HTTP/1.1 722 Host: webdav.example.com 723 Content-Type: application/xml; charset=utf-8 724 Content-Length: xxxx 725 Depth: 1 726 Prefer: return=minimal, depth-noroot 728 729 730 731 732 733 734 735 >> Response << 737 HTTP/1.1 207 Multi-Status 738 Content-Type: application/xml; charset=utf-8 739 Content-Length: xxxx 740 Preference-Applied: return=minimal, depth-noroot 742 743 744 745 /container/work/ 746 747 748 749 750 751 752 HTTP/1.1 200 OK 753 754 755 756 /container/home/ 757 758 759 760 761 762 763 HTTP/1.1 200 OK 764 765 766 767 /container/foo.txt 768 769 770 771 772 HTTP/1.1 200 OK 773 774 775 777 B.1.3. Minimal PROPFIND request/response with an empty DAV:propstat 778 element 780 This example tries to fetch an unknown property from a collection. 782 >> Request << 784 PROPFIND /container/ HTTP/1.1 785 Host: webdav.example.com 786 Content-Type: application/xml; charset=utf-8 787 Content-Length: xxxx 788 Prefer: return=minimal 790 791 792 793 794 795 797 >> Response << 799 HTTP/1.1 207 Multi-Status 800 Content-Type: application/xml; charset=utf-8 801 Content-Length: xxxx 802 Preference-Applied: return=minimal 804 805 806 807 /container/ 808 809 810 HTTP/1.1 200 OK 811 812 813 815 B.2. REPORT 817 B.2.1. Typical REPORT request/response 819 This example tries to fetch an unknown property from several 820 resources via the DAV:expand-property [RFC3253] REPORT type. 822 >> Request << 824 REPORT /dav/principals/ HTTP/1.1 825 Host: webdav.example.com 826 Content-type: text/xml; charset=utf-8 827 Content-length: xxxx 829 830 831 832 833 834 836 838 839 841 842 844 845 847 848 849 851 >> Response << 853 HTTP/1.1 207 Multi-Status 854 Content-Type: application/xml; charset=utf-8 855 Content-Length: xxxx 857 858 862 863 /dav/principals/ 864 865 866 867 868 /dav/principals/user/ken/ 869 870 871 872 873 874 ken 875 876 877 /dav/calendars/user/ken/ 878 879 880 881 882 883 884 HTTP/1.1 200 OK 885 886 887 888 889 890 HTTP/1.1 404 Not Found 891 892 893 894 895 896 /dav/addressbooks/user/ken/ 897 898 899 900 901 902 903 HTTP/1.1 200 OK 904 905 906 907 908 909 HTTP/1.1 404 Not Found 910 911 912 913 914 HTTP/1.1 200 OK 915 916 917 918 919 920 HTTP/1.1 404 Not Found 921 922 923 924 925 HTTP/1.1 200 OK 926 927 928 930 B.2.2. Minimal REPORT request/response 932 This example tries to fetch an unknown property from several 933 resources via the DAV:expand-property [RFC3253] REPORT type. 935 >> Request << 937 REPORT /dav/principals/ HTTP/1.1 938 Host: webdav.example.com 939 Content-Type: application/xml; charset=utf-8 940 Content-Length: xxxx 941 Prefer: return=minimal 943 944 945 946 947 948 950 952 953 955 956 958 959 961 962 963 965 >> Response << 966 HTTP/1.1 207 Multi-Status 967 Content-Type: application/xml; charset=utf-8 968 Content-Length: xxxx 969 Preference-Applied: return=minimal 971 972 976 977 /dav/principals/ 978 979 980 981 982 /dav/principals/user/ken/ 983 984 985 986 987 988 ken 989 990 991 /dav/calendars/user/ken/ 992 993 994 995 996 997 998 HTTP/1.1 200 OK 999 1000 1001 1002 1003 1004 /dav/addressbooks/user/ken/ 1005 1006 1007 1008 1009 1010 1011 HTTP/1.1 200 OK 1012 1013 1015 1016 1017 HTTP/1.1 200 OK 1018 1019 1020 1021 1022 HTTP/1.1 200 OK 1023 1024 1025 1027 B.3. PROPPATCH 1029 B.3.1. Typical PROPPATCH request/response 1031 >> Request << 1033 PROPPATCH /container/ HTTP/1.1 1034 Host: webdav.example.com 1035 Content-Type: application/xml; charset=utf-8 1036 Content-Length: xxxx 1038 1039 1040 1041 1042 My Container 1043 1044 1045 1046 >> Response << 1048 HTTP/1.1 207 Multi-Status 1049 Content-Type: application/xml; charset=utf-8 1050 Content-Length: xxxx 1052 1053 1054 1055 /container/ 1056 1057 1058 1059 1060 HTTP/1.1 200 OK 1061 1062 1063 1065 B.3.2. Minimal PROPPATCH request/response 1067 >> Request << 1069 PROPPATCH /container/ HTTP/1.1 1070 Host: webdav.example.com 1071 Content-Type: application/xml; charset=utf-8 1072 Content-Length: xxxx 1073 Prefer: return=minimal 1075 1076 1077 1078 1079 My Container 1080 1081 1082 1084 >> Response << 1086 HTTP/1.1 200 OK 1087 Content-Length: 0 1088 Preference-Applied: return=minimal 1090 B.4. MKCOL 1092 B.4.1. Verbose MKCOL request/response 1094 >> Request << 1096 MKCOL /container/ HTTP/1.1 1097 Host: webdav.example.com 1098 Content-Type: application/xml; charset=utf-8 1099 Content-Length: xxxx 1101 1102 1103 1104 1105 My Container 1106 1107 1108 1110 >> Response << 1112 HTTP/1.1 201 Created 1113 Cache-Control: no-cache 1114 Content-Type: application/xml; charset=utf-8 1115 Content-Length: xxxx 1117 1118 1119 1120 1121 1122 1123 HTTP/1.1 200 OK 1124 1125 1127 B.4.2. Minimal MKCOL request/response 1128 >> Request << 1130 MKCOL /container/ HTTP/1.1 1131 Host: webdav.example.com 1132 Content-Type: application/xml; charset=utf-8 1133 Content-Length: xxxx 1134 Prefer: return=minimal 1136 1137 1138 1139 1140 My Container 1141 1142 1143 1145 >> Response << 1147 HTTP/1.1 201 Created 1148 Cache-Control: no-cache 1149 Content-Length: 0 1150 Preference-Applied: return=minimal 1152 B.5. POST 1154 B.5.1. Typical resource creation and retrieval via POST + GET 1156 Note that this request is not conditional because by using the POST 1157 [RFC5995] method the client lets the server choose the resource URI, 1158 thereby guaranteeing that it will not modify an existing resource. 1160 >> Request << 1162 POST /container/work;add-member/ HTTP/1.1 1163 Host: caldav.example.com 1164 Content-Type: text/calendar; charset=utf-8 1165 Content-Length: xxxx 1167 BEGIN:VCALENDAR 1168 VERSION:2.0 1169 PRODID:-//Example Corp.//CalDAV Client//EN 1170 BEGIN:VEVENT 1171 UID:CD87465FA 1172 SEQUENCE:0 1173 DTSTAMP:20120602T185254Z 1174 DTSTART:20120602T160000Z 1175 DTEND:20120602T170000Z 1176 TRANSP:OPAQUE 1177 SUMMARY:Lunch 1178 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1179 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1180 mailto:murch@example.com 1181 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1182 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@ 1183 example.com 1184 END:VEVENT 1185 END:VCALENDAR 1187 >> Response << 1189 HTTP/1.1 201 Created 1190 Location: /container/work/abc.ics 1191 Content-Length: 0 1193 Note that the server did not include any validator header fields (e.g 1194 ETag) in the response, signaling that the created representation 1195 differs from the representation sent in the body of the request. The 1196 client has to send a separate GET request to retrieve the current 1197 representation: 1199 >> Request << 1201 GET /container/work/abc.ics HTTP/1.1 1202 Host: caldav.example.com 1203 >> Response << 1205 HTTP/1.1 200 OK 1206 Content-Type: text/calendar; charset=utf-8 1207 Content-Length: xxxx 1208 ETag: "nahduyejc" 1209 Schedule-Tag: "jfd84hgbcn" 1211 BEGIN:VCALENDAR 1212 VERSION:2.0 1213 PRODID:-//Example Corp.//CalDAV Server//EN 1214 BEGIN:VEVENT 1215 UID:CD87465FA 1216 SEQUENCE:0 1217 DTSTAMP:20120602T185300Z 1218 DTSTART:20120602T160000Z 1219 DTEND:20120602T170000Z 1220 TRANSP:OPAQUE 1221 SUMMARY:Lunch 1222 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1223 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1224 mailto:murch@example.com 1225 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1226 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS= 1227 1.2:mailto:jdoe@example.com 1228 END:VEVENT 1229 END:VCALENDAR 1231 B.5.2. Streamlined resource creation and retrieval via POST 1233 Note that this request is not conditional because by using the POST 1234 [RFC5995] method the client lets the server choose the resource URI, 1235 thereby guaranteeing that it will not modify an existing resource. 1237 >> Request << 1239 POST /container/work;add-member/ HTTP/1.1 1240 Host: caldav.example.com 1241 Content-Type: text/calendar; charset=utf-8 1242 Content-Length: xxxx 1243 Prefer: return=representation 1245 BEGIN:VCALENDAR 1246 VERSION:2.0 1247 PRODID:-//Example Corp.//CalDAV Client//EN 1248 BEGIN:VEVENT 1249 UID:CD87465FA 1250 SEQUENCE:0 1251 DTSTAMP:20120602T185254Z 1252 DTSTART:20120602T160000Z 1253 DTEND:20120602T170000Z 1254 TRANSP:OPAQUE 1255 SUMMARY:Lunch 1256 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1257 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1258 mailto:murch@example.com 1259 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1260 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@ 1261 example.com 1262 END:VEVENT 1263 END:VCALENDAR 1264 >> Response << 1266 HTTP/1.1 201 Created 1267 Location: /container/work/abc.ics 1268 Content-Type: text/calendar; charset=utf-8 1269 Content-Length: xxxx 1270 Content-Location: /container/work/abc.ics 1271 ETag: "nahduyejc" 1272 Schedule-Tag: "jfd84hgbcn" 1273 Preference-Applied: return=representation 1275 BEGIN:VCALENDAR 1276 VERSION:2.0 1277 PRODID:-//Example Corp.//CalDAV Server//EN 1278 BEGIN:VEVENT 1279 UID:CD87465FA 1280 SEQUENCE:0 1281 DTSTAMP:20120602T185300Z 1282 DTSTART:20120602T160000Z 1283 DTEND:20120602T170000Z 1284 TRANSP:OPAQUE 1285 SUMMARY:Lunch 1286 ORGANIZER;CN="Ken Murchison":mailto:murch@example.com 1287 ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED: 1288 mailto:murch@example.com 1289 ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT 1290 =NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS= 1291 1.2:mailto:jdoe@example.com 1292 END:VEVENT 1293 END:VCALENDAR 1295 B.6. PUT 1297 B.6.1. Typical conditional resource update failure and retrieval via 1298 PUT + GET 1300 >> Request << 1302 PUT /container/motd.txt HTTP/1.1 1303 Host: dav.example.com 1304 Content-Type: text/plain 1305 Content-Length: xxxx 1306 If-Match: "asd973" 1308 Either write something worth reading or do something worth writing. 1310 >> Response << 1312 HTTP/1.1 412 Precondition Failed 1313 Content-Length: 0 1315 The resource has been modified by another user agent (ETag mismatch), 1316 therefore the client has to send a separate GET request to retrieve 1317 the current representation: 1319 >> Request << 1321 GET /container/motd.txt HTTP/1.1 1322 Host: dav.example.com 1324 >> Response << 1326 HTTP/1.1 200 OK 1327 Content-Type: text/plain 1328 Content-Length: xxxx 1329 ETag: "789sdas" 1331 An investment in knowledge pays the best interest. 1333 B.6.2. Streamlined conditional resource update failure and retrieval 1334 via PUT 1336 >> Request << 1338 PUT /container/motd.txt HTTP/1.1 1339 Host: dav.example.com 1340 Content-Type: text/plain 1341 Content-Length: xxxx 1342 If-Match: "asd973" 1343 Prefer: return=representation 1345 Either write something worth reading or do something worth writing. 1347 >> Response << 1349 HTTP/1.1 412 Precondition Failed 1350 Content-Type: text/plain 1351 Content-Length: xxxx 1352 Content-Location: /container/motd.txt 1353 ETag: "789sdas" 1354 Preference-Applied: return=representation 1356 An investment in knowledge pays the best interest. 1358 Appendix C. Change Log 1360 < RFC Editor: before publication please remove this section > 1362 C.1. Since -13 1364 o More editorial and formatting changes from Julian Reschke. 1366 o Re-introduced RFC 7240 to Abstract per Gen-ART review. 1368 C.2. Since -12 1370 o Several editorial and formatting changes from Julian Reschke. 1372 C.3. Since -11 1374 o Several fixes per Gen-ART Review (Stuart Bryant): 1376 * Added "updates RFC7240" text to Abstract. 1378 * Removed "Open Issues" Section. 1380 * Added RFC Editor note to remove "URIs" Section. 1382 * Fixed typos. 1384 C.4. Since -10 1386 o Pared down Updates per Alexey. 1388 o Added self-reference for 412 status code in registry. 1390 C.5. Since -09 1392 o Combined PROPFIND and REPORT sections 1394 o Added several more RFCs to Updated list. 1396 o Added list of report types that can benefit from "return=minimal". 1398 o Changed REPORT example to use DAV:expand-property. 1400 o Added IANA section to update HTTP Method Registry references. 1402 o Split "return=representation" discussion into two separate 1403 sections and expanded text. 1405 o Updated Open Issues with new questions. 1407 o Several editorial changes from Julian Reschke. 1409 C.6. Since -08 1411 o Moved examples to Appendix B. 1413 o Added reference to HTTP PATCH. 1415 o Updated Implementation Status reference from RFC 6982 to RFC 7942. 1417 C.7. Since -07 1419 o No substantive changes. Refreshed due to pending expiration. 1421 C.8. Since -06 1423 o Updated HTTPbis and Prefer references to published RFCs. 1425 C.9. Since -05 1427 o Allow a minimal PROPFIND/REPORT response to contain a DAV:status 1428 element rather than an empty DAV:propstat element. 1430 o Allow 204 (No Content) as a minimal PROPATCH success response. 1432 o Added justification for why a minimal MKCOL/MKCALENDAR success 1433 response must have an empty body. 1435 o Added text and an example of how "return=representation" can be 1436 employed with a conditional state-changing request and a 412 1437 (Precondition Failed) response. 1439 o Added a note to the POST+GET example bringing attention to the 1440 lack of a validator header field in the POST response. 1442 o Reduced the number of inline references. 1444 o Limited most examples to vanilla WebDAV. 1446 o Reduced number of items in TOC. 1448 o Removed the recommendation that the legacy Brief header 1449 functionality should be implemented. 1451 o Added note about how a server should handle a request that 1452 contains both Brief and Prefer. 1454 o Other editorial tweaks from Julian Reschke. 1456 C.10. Since -04 1458 o Added note stating where to send comments. 1460 C.11. Since -03 1462 o Limited "Updates" to just RFC 4918. 1464 o Consensus from CalConnect membership that a "depth-root" option is 1465 unnecessary at this point. 1467 o Consensus from CalConnect membership to remove Vary header field 1468 from PROPFIND and REPORT responses since these responses don't 1469 appear to be cached. 1471 o Updated "Implementation Status" section boilerplate to RFC 6982. 1473 o Added aCal to "Implementation Status" section. 1475 o Added note that servers SHOULD respond with Preference-Applied 1476 when return=minimal is used with PROPFIND or REPORT. 1478 C.12. Since -02 1480 o Reintroduced "Updates" to header. 1482 o Added text noting that "return=representation" provides a level of 1483 atomicity to the operation. 1485 o Added "Implementation Status" section. 1487 o Tweaked/corrected some examples.. 1489 o Updated HTTPbis references. 1491 C.13. Since -01 1493 o Removed "Updates" from header. 1495 o Fixed some missing/incorrect references. 1497 o Reintroduced Cache-Control:no-cache to MKCOL responses. 1499 C.14. Since -00 1501 o Updated to comply with draft-snell-httpprefer-18. 1503 o Reordered "Minimal REPORT Response" and "Minimal PROPPATCH 1504 Response" sections. 1506 o Added some explanatory text to examples. 1508 C.15. Since CalConnect XXIV 1510 o Updated references. 1512 o Stated that "depth-noroot" can be used in conjuction with 1513 "return=minimal". 1515 o Added text mentioning that "depth-noroot" is based on the MSDN 1516 "1,noroot" and "infinity,noroot" Depth header values. 1518 o The server behavior required when "return=minimal" would result in 1519 zero DAV:propstat elements has been changed 1521 from: 1523 1524 1525 1526 /container/ 1527 HTTP/1.1 200 OK 1528 1529 1530 to the slightly more verbose: 1532 1533 1534 1535 /container/ 1536 1537 1538 HTTP/1.1 200 OK 1539 1540 1541 1543 Author's Address 1545 Kenneth Murchison 1546 Carnegie Mellon University 1547 5000 Forbes Avenue 1548 Pittsburgh, PA 15213 1549 USA 1551 Phone: +1 412 268 1982 1552 Email: murch@andrew.cmu.edu