Independent Submission K. Murchison
Internet-Draft CMU
Updates: 3253, 4918, 5689, 5995 (if July 21, 2014
approved)
Intended status: Standards Track
Expires: January 22, 2015
Use of the Prefer Header Field in Web Distributed Authoring and
Versioning (WebDAV)
draft-murchison-webdav-prefer-07
Abstract
This specification defines how the HTTP Prefer header field can be
used by a WebDAV client to request that certain behaviors be employed
by a server while constructing a response to a request.
Editorial Note (To be removed by RFC Editor before publication)
Please send comments to the Web Distributed Authoring and Versioning
(WebDAV) mailing list at <mailto:w3c-dist-auth@w3.org> [1], which may
be joined by sending a message with subject "subscribe" to
<mailto:w3c-dist-auth-request@w3.org> [2]. This mailing list is
archived at <http://lists.w3.org/Archives/Public/w3c-dist-auth/> [3].
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 22, 2015.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
Murchison Expires January 22, 2015 [Page 1]
Internet-Draft Prefer in WebDAV July 2014
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Reducing WebDAV Response Verbosity with
"return=minimal" . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Minimal PROPFIND Response . . . . . . . . . . . . . . . . 3
2.2. Minimal REPORT Response . . . . . . . . . . . . . . . . . 7
2.3. Minimal PROPPATCH Response . . . . . . . . . . . . . . . 11
2.4. Minimal MKCALENDAR / MKCOL Response . . . . . . . . . . . 13
3. Reducing WebDAV Round-Trips with
"return=representation" . . . . . . . . . . . . . . . . . . . 15
4. The "depth-noroot" Processing Preference . . . . . . . . . . 22
5. Implementation Status . . . . . . . . . . . . . . . . . . . . 26
6. Security Considerations . . . . . . . . . . . . . . . . . . . 27
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 28
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
9.1. Normative References . . . . . . . . . . . . . . . . . . 28
9.2. Informative References . . . . . . . . . . . . . . . . . 29
9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Appendix A. The Brief and Extended Depth Request Header Fields . 30
Appendix B. Change Log (To be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 31
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33
1. Introduction
[RFC7240] defines the HTTP Prefer request header field and the
"return=minimal" preference which indicates that a client wishes for
the server to return a minimal response to a successful request, but
states that what constitutes an appropriate minimal response is left
solely to the discretion of the server. Section 2 of this
specification defines precisely what is expected of a server when
constructing minimal responses to successful WebDAV [RFC4918]
requests.
Murchison Expires January 22, 2015 [Page 2]
Internet-Draft Prefer in WebDAV July 2014
[RFC7240] also defines the "return=representaion" preference which
indicates that a client wishes for the server to include an entity
representing the current state of the resource in the response to a
successful request. Section 3 of this specification makes
recommendations on when this preference should be used by clients and
extends its applicability to 412 (Precondition Failed) [RFC7231]
responses.
Finally, Section 4 of this specifcation defines the "depth-noroot"
preference that can be used with WebDAV methods that support the
"Depth" header field..
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
This document references XML element types in the "DAV:" [RFC4918]
namespace outside of the context of an XML fragment. When doing so,
the string "DAV:" will be prepended to the XML element type.
2. Reducing WebDAV Response Verbosity with "return=minimal"
Some payload bodies in responses to WebDAV requests, such as 207
(Multi-Status) [RFC4918] responses, can be quite verbose or even
unnecessary at times. This specification defines how the Prefer
request header field, in conjunction with its "return=minimal"
preference, can be used by clients to reduce the verbosity of such
responses by requesting that the server omit those portions of the
response that can be inferred by their absence.
2.1. Minimal PROPFIND Response
When a PROPFIND [RFC4918] request contains a Prefer header field with
a preference of "return=minimal", the server SHOULD omit all
DAV:propstat XML elements containing a DAV:status XML element of
value 404 (Not Found) [RFC7231] from the 207 (Multi-Status) response.
If the omission of such a DAV:propstat element would result in a
DAV:response XML element containing zero DAV:propstat elements, the
server MUST substitute one of the following in its place:
o a DAV:propstat element consisting of an empty DAV:prop element and
a DAV:status element of value 200 (OK) [RFC7231]
o a DAV:status element of value 200 (OK)
Murchison Expires January 22, 2015 [Page 3]
Internet-Draft Prefer in WebDAV July 2014
2.1.1. Example: Typical PROPFIND request/response
This example tries to fetch an unknown property from a collection.
>> Request <<
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:resourcetype/>
<X:foobar/>
</D:prop>
</D:propfind>
Murchison Expires January 22, 2015 [Page 4]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</D:multistatus>
2.1.2. Example: Minimal PROPFIND request/response
This example tries to fetch an unknown property from a collection.
Murchison Expires January 22, 2015 [Page 5]
Internet-Draft Prefer in WebDAV July 2014
>> Request <<
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Prefer: return=minimal
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:resourcetype/>
<X:foobar/>
</D:prop>
</D:propfind>
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Preference-Applied: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
2.1.3. Example: Minimal PROPFIND request/response with an empty
DAV:propstat element
This example tries to fetch an unknown property from a collection.
Murchison Expires January 22, 2015 [Page 6]
Internet-Draft Prefer in WebDAV July 2014
>> Request <<
PROPFIND /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Prefer: return=minimal
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:" xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<X:foobar/>
</D:prop>
</D:propfind>
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Preference-Applied: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop/>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
2.2. Minimal REPORT Response
When a REPORT [RFC3253] request, whose report type results in a 207
(Multi-Status) response, contains a Prefer header field with a
preference of "return=minimal", the server SHOULD omit all
DAV:propstat XML elements containing a DAV:status XML element of
value 404 (Not Found) [RFC7231] from the 207 (Multi-Status) response.
If the omission of such a DAV:propstat element would result in a
DAV:response XML element containing zero DAV:propstat elements, the
server MUST substitute one of the following in its place:
Murchison Expires January 22, 2015 [Page 7]
Internet-Draft Prefer in WebDAV July 2014
o a DAV:propstat element consisting of an empty DAV:prop element and
a DAV:status element of value 200 (OK) [RFC7231]
o a DAV:status element of value 200 (OK)
2.2.1. Example: Typical REPORT request/response
This example tries to fetch an unknown property from several
resources via the CALDAV:calendar-multiget [RFC4791] REPORT type.
>> Request <<
REPORT /murch/work/ HTTP/1.1
Host: caldav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<C:calendar-multiget xmlns:C="urn:ietf:params:xml:ns:caldav"
xmlns:D="DAV:"
xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:getetag/>
<X:foobar/>
</D:prop>
<D:href>/murch/work/abc.ics</D:href>
<D:href>/murch/work/qrs.ics</D:href>
<D:href>/murch/work/xyz.ics</D:href>
</C:calendar-multiget>
Murchison Expires January 22, 2015 [Page 8]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:"
xmlns:X="http://ns.example.com/foobar/">
<D:response>
<D:href>/murch/work/abc.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"jahsd823ru"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/murch/work/qrs.ics</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:response>
<D:response>
<D:href>/murch/work/xyz.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"p08ulkj"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<X:foobar/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
</D:multistatus>
Murchison Expires January 22, 2015 [Page 9]
Internet-Draft Prefer in WebDAV July 2014
2.2.2. Example: Minimal REPORT request/response
This example tries to fetch an unknown property from several
resources via the CALDAV:calendar-multiget [RFC4791] REPORT type.
>> Request <<
REPORT /murch/work/ HTTP/1.1
Host: caldav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Prefer: return=minimal
<?xml version="1.0" encoding="utf-8" ?>
<C:calendar-multiget xmlns:C="urn:ietf:params:xml:ns:caldav"
xmlns:D="DAV:"
xmlns:X="http://ns.example.com/foobar/">
<D:prop>
<D:getetag/>
<X:foobar/>
</D:prop>
<D:href>/murch/work/abc.ics</D:href>
<D:href>/murch/work/qrs.ics</D:href>
<D:href>/murch/work/xyz.ics</D:href>
</C:calendar-multiget>
Murchison Expires January 22, 2015 [Page 10]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Preference-Applied: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/murch/work/abc.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"jahsd823ru"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/murch/work/qrs.ics</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:response>
<D:response>
<D:href>/murch/work/xyz.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"p08ulkj"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
2.3. Minimal PROPPATCH Response
When a PROPPATCH [RFC4918] request contains a Prefer header field
with a preference of "return=minimal", and all instructions are
processed successfully, the server SHOULD return one of the following
responses rather than a 207 (Multi-Status) response:
o 204 (No Content) [RFC7231]
o 200 (OK) [RFC7231] (preferably with a zero-length message body)
Murchison Expires January 22, 2015 [Page 11]
Internet-Draft Prefer in WebDAV July 2014
2.3.1. Example: Typical PROPPATCH request/response
>> Request <<
PROPPATCH /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:propertyupdate>
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop>
<D:displayname/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
2.3.2. Example: Minimal PROPPATCH request/response
Murchison Expires January 22, 2015 [Page 12]
Internet-Draft Prefer in WebDAV July 2014
>> Request <<
PROPPATCH /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Prefer: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:propertyupdate xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:propertyupdate>
>> Response <<
HTTP/1.1 200 OK
Content-Length: 0
Preference-Applied: return=minimal
2.4. Minimal MKCALENDAR / MKCOL Response
Both the MKCALENDAR [RFC4791] and Extended MKCOL [RFC5689]
specifications indicate that a server MAY return a message body in
response to a successful request. This specification explicitly
defines the intended behavior in the presence of the Prefer header
field.
When a MKCALENDAR or an Extended MKCOL request contains a Prefer
header field with a preference of "return=minimal", and the
collection is created with all requested properties being set
successfully, the server SHOULD return a 201 (Created) [RFC7231]
response with an empty (zero-length) message body.
Note that the rationale for requiring that a minimal success response
have an empty body is twofold:
o [RFC4791] Section 5.3.1 states: "If a response body for a
successful [MKCALENDAR] request is included, it MUST be a
CALDAV:mkcalendar-response XML element."
Murchison Expires January 22, 2015 [Page 13]
Internet-Draft Prefer in WebDAV July 2014
o [RFC5689] Section 3 states: "When an empty response body is
returned with a success request status code, the client can assume
that all properties were set."
2.4.1. Example: Verbose MKCOL request/response
>> Request <<
MKCOL /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
>> Response <<
HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol-response xmlns:D="DAV:">
<D:propstat>
<D:prop>
<D:displayname/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:mkcol-response>
2.4.2. Example: Minimal MKCOL request/response
Murchison Expires January 22, 2015 [Page 14]
Internet-Draft Prefer in WebDAV July 2014
>> Request <<
MKCOL /container/ HTTP/1.1
Host: webdav.example.com
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Prefer: return=minimal
<?xml version="1.0" encoding="utf-8"?>
<D:mkcol xmlns:D="DAV:">
<D:set>
<D:prop>
<D:displayname>My Container</D:displayname>
</D:prop>
</D:set>
</D:mkcol>
>> Response <<
HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 0
Preference-Applied: return=minimal
3. Reducing WebDAV Round-Trips with "return=representation"
The PUT, COPY, MOVE, [RFC4918] and POST [RFC5995] methods can be used
to create or update a resource. In some instances, such as with
CalDAV Scheduling [RFC6638], the created or updated resource
representation may differ from the representation sent in the body of
the request or referenced by the effective request URI. In cases
where the client would normally issue a subsequent GET request to
retrieve the current representation of the resource, the client
SHOULD instead include a Prefer header field with the
"return=representation" preference in the PUT, COPY, MOVE, or POST
request. By doing this, the client can coalesce the create/update
and retrieve operations into one round-trip rather than two. An
additional benefit of using "return=representation" in such a request
is that the client will know that any changes to the resource were
produced by the server rather than a concurrent client, thus
providing a level of atomicity to the operation.
Murchison Expires January 22, 2015 [Page 15]
Internet-Draft Prefer in WebDAV July 2014
Frequently, clients using a state-changing method such as those above
will make them conditional by including either an If-Match or If-
None-Match [RFC7232] header field in the request. If the specified
condition evaluates to false, and the request includes a Prefer
header field with the "return=representation" preference, the server
SHOULD include an entity representing the current state of the
resource in the resulting 412 (Precondition Failed) [RFC7231]
response.
3.1. Example: Typical resource creation and retrieval via POST + GET
Note that this request is not conditional because by using the POST
[RFC5995] method the client lets the server choose the URI, thereby
guaranteeing that it will not modify an existing resource.
>> Request <<
POST /murch/work;add-member/ HTTP/1.1
Host: caldav.example.com
Content-Type: text/calendar; charset=utf-8
Content-Length: xxxx
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185254Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@
example.com
END:VEVENT
END:VCALENDAR
Murchison Expires January 22, 2015 [Page 16]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 201 Created
Location: /murch/work/abc.ics
Content-Length: 0
Note that the server did not include any validator header fields (e.g
ETag) in the response, signaling that the created representation
differs from the representation sent in the body of the request. The
client has to send a separate GET request to retrieve the current
representation:
>> Request <<
GET /murch/work/abc.ics HTTP/1.1
Host: caldav.example.com
Murchison Expires January 22, 2015 [Page 17]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 200 OK
Content-Type: text/calendar; charset=utf-8
Content-Length: xxxx
ETag: "nahduyejc"
Schedule-Tag: "jfd84hgbcn"
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185300Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS=
1.2:mailto:jdoe@example.com
END:VEVENT
END:VCALENDAR
3.2. Example: Streamlined resource creation and retrieval via POST
Note that this request is not conditional because by using the POST
[RFC5995] method the client lets the server choose the URI, thereby
guaranteeing that it will not modify an existing resource.
Murchison Expires January 22, 2015 [Page 18]
Internet-Draft Prefer in WebDAV July 2014
>> Request <<
POST /murch/work;add-member/ HTTP/1.1
Host: caldav.example.com
Content-Type: text/calendar; charset=utf-8
Content-Length: xxxx
Prefer: return=representation
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185254Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:jdoe@
example.com
END:VEVENT
END:VCALENDAR
Murchison Expires January 22, 2015 [Page 19]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 201 Created
Location: /murch/work/abc.ics
Content-Type: text/calendar; charset=utf-8
Content-Length: xxxx
Content-Location: /murch/work/abc.ics
ETag: "nahduyejc"
Schedule-Tag: "jfd84hgbcn"
Preference-Applied: return=representation
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Server//EN
BEGIN:VEVENT
UID:CD87465FA
SEQUENCE:0
DTSTAMP:20120602T185300Z
DTSTART:20120602T160000Z
DTEND:20120602T170000Z
TRANSP:OPAQUE
SUMMARY:Lunch
ORGANIZER;CN="Ken Murchison":mailto:murch@example.com
ATTENDEE;CN="Ken Murchison";CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED:
mailto:murch@example.com
ATTENDEE;CN="John Doe";CUTYPE=INDIVIDUAL;PARTSTAT
=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS=
1.2:mailto:jdoe@example.com
END:VEVENT
END:VCALENDAR
3.3. Example: Typical conditional resource update failure and retrieval
via PUT + GET
>> Request <<
PUT /container/motd.txt HTTP/1.1
Host: dav.example.com
Content-Type: text/plain
Content-Length: xxxx
If-Match: "asd973"
Either write something worth reading or do something worth writing.
Murchison Expires January 22, 2015 [Page 20]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 412 Precondition Failed
Content-Length: 0
The resource has been modified by another user agent (ETag mismatch),
therefore the client has to send a separate GET request to retrieve
the current representation:
>> Request <<
GET /container/motd.txt HTTP/1.1
Host: dav.example.com
>> Response <<
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: xxxx
ETag: "789sdas"
An investment in knowledge pays the best interest.
3.4. Example: Streamlined conditional resource update failure and
retrieval via PUT
>> Request <<
PUT /container/motd.txt HTTP/1.1
Host: dav.example.com
Content-Type: text/plain
Content-Length: xxxx
If-Match: "asd973"
Prefer: return=representation
Either write something worth reading or do something worth writing.
Murchison Expires January 22, 2015 [Page 21]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 412 Precondition Failed
Content-Type: text/plain
Content-Length: xxxx
Content-Location: /container/motd.txt
ETag: "789sdas"
Preference-Applied: return=representation
An investment in knowledge pays the best interest.
4. The "depth-noroot" Processing Preference
The "depth-noroot" preference indicates that the client wishes for
the server to exclude the target (root) resource from processing by
the WebDAV method and only apply the WebDAV method to the target
resource's subordinate resources.
depth-noroot = "depth-noroot"
This preference is only intended to be used with WebDAV methods whose
definitions explicitly provide support for the Depth [RFC4918] header
field. Furthermore, this preference only applies when the Depth
header field has a value of "1" or "infinity" (either implicitly or
explicitly).
The "depth-noroot" preference MAY be used in conjunction with the
"return=minimal" preference in a single request.
4.1. Example: Typical PROPFIND request/response with Depth:1
This example fetches the DAV:resourcetype [RFC4918] property for a
collection and its child resources.
Murchison Expires January 22, 2015 [Page 22]
Internet-Draft Prefer in WebDAV July 2014
>> Request <<
PROPFIND /murch/ HTTP/1.1
Host: webdav.example.com
Content-Type: text/xml
Content-Length: xxx
Depth: 1
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:resourcetype/>
</D:prop>
</D:propfind>
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/murch/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/murch/work/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
Murchison Expires January 22, 2015 [Page 23]
Internet-Draft Prefer in WebDAV July 2014
<D:response>
<D:href>/murch/home/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/murch/foo.txt</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
4.2. Example: PROPFIND request/response with Depth:1 and Prefer:depth-
noroot
This example fetches the DAV:resourcetype [RFC4918] property for just
the child resources.
>> Request <<
PROPFIND /murch/ HTTP/1.1
Host: webdav.example.com
Content-Type: text/xml
Content-Length: xxx
Depth: 1
Prefer: depth-noroot
<?xml version="1.0" encoding="UTF-8"?>
<D:propfind xmlns:D="DAV:">
<D:prop>
<D:resourcetype/>
</D:prop>
</D:propfind>
Murchison Expires January 22, 2015 [Page 24]
Internet-Draft Prefer in WebDAV July 2014
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
Preference-Applied: depth-noroot
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/murch/work/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/murch/home/</D:href>
<D:propstat>
<D:prop>
<D:resourcetype>
<D:collection/>
</D:resourcetype>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href>/murch/foo.txt</D:href>
<D:propstat>
<D:prop>
<D:resourcetype/>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
Murchison Expires January 22, 2015 [Page 25]
Internet-Draft Prefer in WebDAV July 2014
5. Implementation Status
[RFC Editor: before publication please remove this section and the
reference to [RFC6982]]
This section records the status of known implementations of the
protocol defined by this specification at the time of posting of this
Internet-Draft, and is based on a proposal described in [RFC6982].
The description of implementations in this section is intended to
assist the IETF in its decision processes in progressing drafts to
RFCs. Please note that the listing of any individual implementation
here does not imply endorsement by the IETF. Furthermore, no effort
has been spent to verify the information presented here that was
supplied by IETF contributors. This is not intended as, and must not
be construed to be, a catalog of available implementations or their
features. Readers are advised to note that other implementations may
exist.
According to [RFC6982], "this will allow reviewers and working groups
to assign due consideration to documents that have the benefit of
running code, which may serve as evidence of valuable experimentation
and feedback that have made the implemented protocols more mature.
It is up to the individual working groups to use this information as
they see fit".
5.1. Cyrus
The open source Cyrus [4] project is a highly scalable enterprise
mail system which also supports calendaring and contacts. This beta
level CalDAV/CardDAV implementation supports all of the preferences
described in this document and successfully interoperates with the
CalDAVTester and aCal client implementations described below. This
implementation is freely distributable under a BSD style license from
Computing Services at Carnegie Mellon University [5].
5.2. Calendar and Contacts Server
The open source Calendar and Contacts Server [6] project is a
standards-compliant server implementing the CalDAV and CardDAV
protocols. This production level implementation supports all of the
preferences described in this document and successfully interoperates
with the CalDAVTester client implementation described below. This
implementation is freely distributable under the terms of the Apache
License, Version 2.0 [7].
Murchison Expires January 22, 2015 [Page 26]
Internet-Draft Prefer in WebDAV July 2014
5.3. Bedework
Bedework [8] is an open-source enterprise calendar system that
supports public, personal, and group calendaring. This production
level implementation supports the "return=minimal" preference
described in this document and successfully interoperates with the
CalDAVTester client implementation described below. This
implementation is freely distributable under the Jasig Licensing
Policy [9].
5.4. DAViCal
DAViCal [10] is a server for calendar sharing using the CalDAV
protocol. This production level implementation supports the
"return=minimal" preference described in this document and
successfully interoperates with the CalDAVTester client
implementation described below. This implementation is Free Software
[11] distributable under the General Public License [12].
5.5. aCal
aCal [13] is an open source calendar client for Android which uses
the CalDAV standard for communication. This implementation makes
some use of each of the preferences described in this document and
successfully interoperates with the Cyrus server implementation
described above. This implementation is freely distributable under
the General Public License [14].
5.6. CalDAVTester
CalDAVTester [15] is an open source test and performance application
designed to work with CalDAV and/or CardDAV servers and tests various
aspects of their protocol handling as well as performance. This
widely used implementation supports all of the preferences described
in this document and successfully interoperates with the server
implementations described above. This implementation is freely
distributable under the terms of the Apache License, Version 2.0
[16].
6. Security Considerations
No new security considerations are introduced by use of the Prefer
header field with WebDAV request methods, beyond those discussed in
[RFC7240] and those already inherent in those methods.
Murchison Expires January 22, 2015 [Page 27]
Internet-Draft Prefer in WebDAV July 2014
7. IANA Considerations
The following preference is to be added to the Preferences Registry
defined in [RFC7240].
o Preference: depth-noroot
o Description: The "depth-noroot" preference indicates that the
client wishes for the server to exclude the target (root) resource
from processing by the WebDAV method and only apply the WebDAV
method to the target resource's subordinate resources.
o Reference: Section 4
o Notes: This preference is only intended to be used with WebDAV
methods whose definitions explicitly provide support for the
"Depth" [RFC4918] header field. Furthermore, this preference only
applies when the "Depth" header field has a value of "1" or
"infinity" (either implicitly or explicitly).
8. Acknowledgements
The author would like to thank the following individuals for
contributing their ideas and support for writing this specification:
Cyrus Daboo, Helge Hess, Andrew McMillan, Arnaud Quillaud, and Julian
Reschke.
The author would also like to thank the Calendaring and Scheduling
Consortium for advice with this specification, and for organizing
interoperability testing events to help refine it.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
Whitehead, "Versioning Extensions to WebDAV
(Web Distributed Authoring and Versioning)", RFC 3253,
March 2002.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
March 2007.
Murchison Expires January 22, 2015 [Page 28]
Internet-Draft Prefer in WebDAV July 2014
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
[RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
and Versioning (WebDAV)", RFC 5689, September 2009.
[RFC5995] Reschke, J., "Using POST to Add Members to Web Distributed
Authoring and Versioning (WebDAV) Collections", RFC 5995,
September 2010.
[RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", RFC 7231, June 2014.
[RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Conditional Requests", RFC 7232, June 2014.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, June 2014.
9.2. Informative References
[MSDN.aa493854]
Microsoft Developer Network, "PROPPATCH Method", June
2006,
<http://msdn.microsoft.com/en-us/library/aa493854.aspx>.
[MSDN.aa563501]
Microsoft Developer Network, "Brief Header", June 2006,
<http://msdn.microsoft.com/en-us/library/aa563501.aspx>.
[MSDN.aa563950]
Microsoft Developer Network, "Depth Header", June 2006,
<http://msdn.microsoft.com/en-us/library/aa563950.aspx>.
[MSDN.aa580336]
Microsoft Developer Network, "PROPFIND Method", June 2006,
<http://msdn.microsoft.com/en-us/library/aa580336.aspx>.
[RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
CalDAV", RFC 6638, June 2012.
[RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", RFC 6982, July
2013.
Murchison Expires January 22, 2015 [Page 29]
Internet-Draft Prefer in WebDAV July 2014
9.3. URIs
[1] http://www.cyrusimap.org/
[2] http://www.cmu.edu/computing/
[3] http://calendarserver.org/
[4] http://www.apache.org/licenses/LICENSE-2.0.html
[5] http://www.bedework.org/
[6] http://www.jasig.org/licensing
[7] http://www.davical.org/
[8] http://www.gnu.org/philosophy/open-source-misses-the-point.html
[9] http://www.gnu.org/licenses/gpl.html
[10] http://www.acal.me/
[11] http://www.gnu.org/licenses/gpl.html
[12] http://calendarserver.org/wiki/CalDAVTester
[13] http://www.apache.org/licenses/LICENSE-2.0.html
Appendix A. The Brief and Extended Depth Request Header Fields
This document is based heavily on the Brief [MSDN.aa563501] and
extended Depth [MSDN.aa563950] request header fields. The behaviors
described in Section 2.1 and Section 2.3 are identical to those
provided by the Brief header field when used with the PROPFIND
[MSDN.aa580336] and PROPPATCH [MSDN.aa493854] methods respectively.
The behavior described in Section 4 is identical to that provided by
the "1,noroot" [MSDN.aa563950] and "infinity,noroot" [MSDN.aa563950]
Depth header field values.
Client and server implementations that already support the Brief
header field can add support for the "return=minimal" preference with
nominal effort.
If a server supporting the Prefer header field receives both the
Brief and Prefer header fields in a request, it MUST ignore the Brief
header field and only use the Prefer header field preferences.
Murchison Expires January 22, 2015 [Page 30]
Internet-Draft Prefer in WebDAV July 2014
Appendix B. Change Log (To be removed by RFC Editor before publication)
B.1. Since -06
o Updated HTTPbis and Prefer references to published RFCs.
B.2. Since -05
o Allow a minimal PROPFIND/REPORT response to contain a DAV:status
element rather than an empty DAV:propstat element.
o Allow 204 (No Content) as a minimal PROPATCH success response.
o Added justification for why a minimal MKCOL/MKCALENDAR success
response must have an empty body.
o Added text and an example of how "return=representation" can be
employed with a conditional state-changing request and a 412
(Precondition Failed) response.
o Added a note to the POST+GET example bringing attention to the
lack of a validator header field in the POST response.
o Reduced the number of inline references.
o Limited most examples to vanilla WebDAV.
o Reduced number of items in TOC.
o Removed the recommendation that the legacy Brief header
functionality should be implemented.
o Added note about how a server should handle a request that
contains both Brief and Prefer.
o Other editorial tweaks from Julian Reschke.
B.3. Since -04
o Added note stating where to send comments.
B.4. Since -03
o Limited "Updates" to just RFC 4918.
o Consensus from CalConnect membership that a "depth-root" option is
unnecessary at this point.
Murchison Expires January 22, 2015 [Page 31]
Internet-Draft Prefer in WebDAV July 2014
o Consensus from CalConnect membership to remove Vary header field
from PROPFIND and REPORT responses since these responses don't
appear to be cached.
o Updated "Implementation Status" section boilerplate to RFC 6982.
o Added aCal to "Implementation Status" section.
o Added note that servers SHOULD respond with Preference-Applied
when return=minimal is used with PROPFIND or REPORT.
B.5. Since -02
o Reintroduced "Updates" to header.
o Added text noting that "return=representation" provides a level of
atomicity to the operation.
o Added "Implementation Status" section.
o Tweaked/corrected some examples..
o Updated HTTPbis references.
B.6. Since -01
o Removed "Updates" from header.
o Fixed some missing/incorrect references.
o Reintroduced Cache-Control:no-cache to MKCOL responses.
B.7. Since -00
o Updated to comply with draft-snell-httpprefer-18.
o Reordered "Minimal REPORT Response" and "Minimal PROPPATCH
Response" sections.
o Added some explanatory text to examples.
B.8. Since CalConnect XXIV
o Updated references.
o Stated that "depth-noroot" can be used in conjuction with
"return=minimal".
Murchison Expires January 22, 2015 [Page 32]
Internet-Draft Prefer in WebDAV July 2014
o Added text mentioning that "depth-noroot" is based on the MSDN
"1,noroot" and "infinity,noroot" Depth header values.
o The server behavior required when "return=minimal" would result in
zero DAV:propstat elements has been changed
from:
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
</D:response>
</D:multistatus>
to the slightly more verbose:
<?xml version="1.0" encoding="utf-8"?>
<D:multistatus xmlns:D="DAV:">
<D:response>
<D:href>/container/</D:href>
<D:propstat>
<D:prop/>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
</D:multistatus>
Author's Address
Kenneth Murchison
Carnegie Mellon University
5000 Forbes Avenue
Pittsburgh, PA 15213
US
Email: murch@andrew.cmu.edu
Murchison Expires January 22, 2015 [Page 33]