]>
Use of the Prefer Header Field in Web Distributed Authoring and
Versioning (WebDAV)
Carnegie Mellon University
5000 Forbes AvenuePittsburghPA15213USA+1 412 268 1982murch@andrew.cmu.eduApplications and Real-Time
I-DhttppreferwebdavcaldavThis document defines an update to the HTTP Prefer header
field to specify how it can be used by
a WebDAV client to request that certain behaviors be employed by
a server while constructing a response to a request. Furthermore,
it defines the new "depth-noroot" preference.Please send comments to the Web Distributed Authoring and
Versioning (WebDAV) mailing list at
<mailto:w3c-dist-auth@w3.org>,
which may be joined by sending a message with subject
"subscribe" to
<mailto:w3c-dist-auth-request@w3.org>.
This mailing list is archived at
<http://lists.w3.org/Archives/Public/w3c-dist-auth/>.
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.
of this specification defines
precisely what is expected of a server when constructing
minimal responses to successful WebDAV requests. also defines
the "return=representation"
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.
of this specification makes
recommendations on when this preference should be used by
clients and extends its applicability to 412 (Precondition
Failed) responses.Finally, of this specification defines
the "depth-noroot" preference that can be used with WebDAV
methods that support the "Depth" header field.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 .This document references XML element types in the
"DAV:", "urn:ietf:params:xml:ns:caldav", and
"urn:ietf:params:xml:ns:carddav"
namespaces outside of
the context of an XML fragment. When doing so, the strings
"DAV:", "CALDAV:", and "CARDDAV:" will be
prepended to the XML element types respectively.Some payload bodies in responses
to WebDAV requests, such
as 207 (Multi-Status) 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.When a PROPFIND
request, or a REPORT 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) 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:
a DAV:propstat element consisting of an empty DAV:prop
element and a DAV:status element of value 200
(OK)a DAV:status element of value 200 (OK)The following report types are candidates that could
benefit from use of the "return=minimal" preference. NOTE:
This list is not intended to be normative or exhaustive.
DAV:expand-propertyDAV:acl-principal-prop-setDAV:principal-property-searchDAV:sync-collectionCALDAV:calendar-queryCALDAV:calendar-multigetCARDDAV:addressbook-queryCARDDAV:addressbook-multigetSee and
for examples.When a PROPPATCH 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:
204 (No
Content)200
(OK) (preferably with a zero-length message body)See for examples.Both the MKCALENDAR and
Extended MKCOL 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) 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:
Section 5.3.1 states: "If a
response body for a successful request is included, it
MUST be a CALDAV:mkcalendar-response XML element." 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."See for examples. describes the "return=representation"
preference as being intended to provide a means of optimizing
communication between the client and server by eliminating the
need for a subsequent GET request to retrieve the current
representation of the resource following a modification. This
preference is equally applicable to situations where the server
itself modifies a resource, and where a resource has been
modified by another client.The state-changing methods PUT,
COPY/MOVE,
PATCH,
and POST can be used to
create or update a resource. In some instances, such as
with CalDAV
Scheduling, 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, upon receiving a
2xx (Successful) response
to its state-changing request, would normally issue a
subsequent GET request to retrieve the current representation
of the resource, the client can instead include a Prefer
header field with the "return=representation" preference in
the state-changing request.When a state-changing request contains a Prefer header field
with a preference of "return=representation", and the resource
is created or updated successfully, the server SHOULD include
an entity representing the current state resource in the
resulting 201 (Created) or 200
(OK) response. In addition to coalescing the
create/update and retrieve operations into a single
round-trip, by returning the current representation of the
resource in the response 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.See for examples.Frequently, clients using a state-changing method such as
those listed above will make them conditional by including
either an If-Match or
If-None-Match header field in the request. This is done
to prevent the client from accidentally overwriting a
resource whose current state has been modified by another
client acting in parallel. In cases
where the client, upon receiving a 412
(Precondition Failed) response to its conditional
state-changing request, would normally issue a subsequent GET request
to retrieve the current representation of the resource, the
client can instead include a Prefer header field with the
"return=representation" preference in the conditional
state-changing request.When a conditional state-changing request contains a Prefer
header field with a preference of "return=representation", and
the specified condition evaluates to false, the server SHOULD
include an entity representing the current state of the
resource in the resulting 412
(Precondition Failed) response.See for examples.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.This preference is only intended to be used with WebDAV
methods whose definitions explicitly provide support for the
Depth 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.See for examples.< RFC Editor: before publication please remove this section,
the reference to , and section 9.3
("URIs")>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 . 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 ,
"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".The open source Cyrus project is a
highly scalable enterprise mail system which also supports
calendaring and contacts. This production level CalDAV/CardDAV
implementation supports all of the preferences described in
this document and successfully interoperates with the , , and client
implementations described below. This implementation is
freely distributable under a BSD style license from
Computing
Services at Carnegie Mellon University.The open
source Calendar
and Contacts Server 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 and client implementations described below. This
implementation is freely distributable under the terms of
the Apache
License, Version 2.0.Bedework
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 client
implementation described below. This implementation is
freely distributable under the Jasig Licensing
Policy.DAViCal
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 client implementation
described below. This implementation is Free
Software distributable under the General Public
License.The widely used Apple Calendar and Apple
Contacts clients are standards-compliant
clients implementing the CalDAV and CardDAV protocols
respectively. These production level implementations
support the "return=minimal" preference described in this
document and successfully interoperate with the and implementations described above. These
client implementations are proprietary and are distributed
as part of Apple's desktop operating systems.aCal
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 server implementation described above. This
implementation is freely distributable under the General Public
License.
CalDAVTester 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.No new security considerations are introduced by use of the
Prefer header field with WebDAV request methods, beyond those
discussed in and those
already inherent in those methods.The following preference is to be added to the HTTP Preferences
Registry defined in Section 5.1 of .depth-norootThe "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.RFCXXXX, This preference is only intended to be used with WebDAV
methods whose definitions explicitly provide support for the
"Depth" header field.
Furthermore, this preference only applies when the "Depth"
header field has a value of "1" or "infinity" (either
implicitly or explicitly).The following methods are to have their references updated
in the HTTP Method Registry ().Method NameReferencesMKCALENDARRFC4791, Section 5.3.1; RFCXXXX, MKCOLRFC4918, Section 9.3; RFC 5689, Section 3;
RFCXXXX, PROPFINDRFC4918, Section 9.1; RFCXXXX, PROPPATCHRFC4918, Section 9.2; RFCXXXX, REPORTRFC3253, Section 3.6; RFCXXXX, The following status code is to have its references updated
in the HTTP Status Code Registry ().ValueReferences412RFC7232, Section 4.2; RFCXXXX, 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.
&rfc2119;
&rfc3253;
&rfc4791;
&rfc4918;
&rfc5689;
&rfc5789;
&rfc5995;
&rfc7231;
&rfc7232;
&rfc7240;
&rfc3744;
&rfc6352;
&rfc6578;
&rfc6638;
&rfc7942;
Brief HeaderMicrosoft Developer NetworkPROPFIND MethodMicrosoft Developer NetworkPROPPATCH MethodMicrosoft Developer NetworkDepth HeaderMicrosoft Developer NetworkThis document is based heavily on
the Brief
and extended Depth request header
fields. The behaviors described in
and are identical to those provided
by the Brief header field when used with
the PROPFIND
and PROPPATCH methods
respectively. The behavior described in
is identical to that provided by
the "1,noroot"
and "infinity,noroot" 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, clients can
expect the server to ignore the Brief header field and only use
the Prefer header field preferences.This example tries to fetch one known and one unknown
property from child resources.>> Request <<
]]>>> Response <</container/HTTP/1.1 200 OKHTTP/1.1 404 Not Found/container/work/HTTP/1.1 200 OKHTTP/1.1 404 Not Found/container/home/HTTP/1.1 200 OKHTTP/1.1 404 Not Found/container/foo.txtHTTP/1.1 200 OKHTTP/1.1 404 Not Found
]]>This example tries to fetch one known and one unknown
property from child resources only.>> Request <<
]]>>> Response <</container/work/HTTP/1.1 200 OK/container/home/HTTP/1.1 200 OK/container/foo.txtHTTP/1.1 200 OK
]]>This example tries to fetch an unknown property from
a collection.>> Request <<
]]>>> Response <</container/HTTP/1.1 200 OK
]]>This example tries to fetch an unknown property from
several resources via the DAV:expand-property REPORT type.>> Request <<
]]>>> Response <</dav/principals//dav/principals/user/ken/ken/dav/calendars/user/ken/HTTP/1.1 200 OKHTTP/1.1 404 Not Found/dav/addressbooks/user/ken/HTTP/1.1 200 OKHTTP/1.1 404 Not FoundHTTP/1.1 200 OKHTTP/1.1 404 Not FoundHTTP/1.1 200 OK
]]>This example tries to fetch an unknown property from
several resources via the DAV:expand-property REPORT type.>> Request <<
]]>>> Response <</dav/principals//dav/principals/user/ken/ken/dav/calendars/user/ken/HTTP/1.1 200 OK/dav/addressbooks/user/ken/HTTP/1.1 200 OKHTTP/1.1 200 OKHTTP/1.1 200 OK
]]>>> Request <<My Container
]]>>> Response <</container/HTTP/1.1 200 OK
]]>>> Request <<My Container
]]>>> Response <<>> Request <<My Container
]]>>> Response <<HTTP/1.1 200 OK
]]>>> Request <<My Container
]]>>> Response <<Note that this request is not conditional because by using
the POST method the client lets
the server choose the resource URI, thereby guaranteeing that it will
not modify an existing resource.>> Request <<>> Response <<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 <<>> Response <<Note that this request is not conditional because by using
the POST method the client lets
the server choose the resource URI, thereby guaranteeing that it will
not modify an existing resource.>> Request <<>> Response <<>> Request <<>> Response <<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 <<>> Response <<>> Request <<>> Response <<< RFC Editor: before publication please remove this
section >More editorial and formatting changes from Julian Reschke.Re-introduced RFC 7240 to Abstract per Gen-ART review.Several editorial and formatting changes from Julian Reschke.Several fixes per Gen-ART Review (Stuart Bryant):
Added "updates RFC7240" text to Abstract.Removed "Open Issues" Section.Added RFC Editor note to remove "URIs" Section.Fixed typos.Pared down Updates per Alexey.Added self-reference for 412 status code in registry.Combined PROPFIND and REPORT sectionsAdded several more RFCs to Updated list.Added list of report types that can benefit from
"return=minimal".Changed REPORT example to use DAV:expand-property.Added IANA section to update HTTP Method Registry
references.Split "return=representation" discussion into two separate
sections and expanded text.Updated Open Issues with new questions.Several editorial changes from Julian Reschke.Moved examples to Appendix B.Added reference to HTTP PATCH.Updated Implementation Status reference from RFC 6982 to
RFC 7942.No substantive changes. Refreshed due to pending expiration.Updated HTTPbis and Prefer references to published RFCs.Allow a minimal PROPFIND/REPORT response to contain a
DAV:status element rather than an empty DAV:propstat
element.Allow 204 (No Content) as a minimal PROPATCH success
response.Added justification for why a minimal MKCOL/MKCALENDAR
success response must have an empty body.Added text and an example of how "return=representation"
can be employed with a conditional state-changing request
and a 412 (Precondition Failed) response.Added a note to the POST+GET example bringing attention
to the lack of a validator header field in the POST
response.Reduced the number of inline references.Limited most examples to vanilla WebDAV.Reduced number of items in TOC.Removed the recommendation that the legacy Brief header
functionality should be implemented.Added note about how a server should handle a request
that contains both Brief and Prefer.Other editorial tweaks from Julian Reschke.Added note stating where to send comments.Limited "Updates" to just RFC 4918.Consensus from CalConnect membership that a
"depth-root" option is unnecessary at this point.Consensus from CalConnect membership to remove Vary
header field from PROPFIND and REPORT responses since
these responses don't appear to be cached.Updated "Implementation Status" section boilerplate to
RFC 6982.Added aCal to "Implementation Status" section.Added note that servers SHOULD respond with
Preference-Applied when return=minimal is used with
PROPFIND or REPORT.Reintroduced "Updates" to header.Added text noting that "return=representation" provides
a level of atomicity to the operation.Added "Implementation Status" section.Tweaked/corrected some examples..Updated HTTPbis references.Removed "Updates" from header.Fixed some missing/incorrect references.Reintroduced Cache-Control:no-cache to MKCOL responses.Updated to comply with draft-snell-httpprefer-18.Reordered "Minimal REPORT Response" and "Minimal
PROPPATCH Response" sections.Added some explanatory text to examples.Updated references.Stated that "depth-noroot" can be used in conjuction
with "return=minimal".Added text mentioning that "depth-noroot" is based on
the MSDN "1,noroot" and "infinity,noroot" Depth header
values.The server behavior required when "return=minimal" would
result in zero DAV:propstat elements has been changed
from:/container/HTTP/1.1 200 OK
]]>
to the slightly more verbose:/container/HTTP/1.1 200 OK
]]>