]> Carnegie Mellon University

5000 Forbes Avenue Pittsburgh PA 15213 US murch@andrew.cmu.edu

Applications Independent Submission I-D webdav http prefer This specification defines how the HTTP Prefer header can be used by a WebDAV client to request that certain behaviors be implemented by a server while constructing a response to a successful request.

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-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. The behavior of this preference with WebDAV requests needs no further clarification, but of this specification makes recommendations on when it should be used by clients. Finally, of this specifcation 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 elements types in the "DAV:" namespace outside of the context of an XML fragment. When doing so, the string "DAV:" will be prepended to the XML element type.

Some payload bodies in responses to WebDAV requests, such as 207 (Multi-Status) responses, can be quite verbose while entire payload bodies included in some success responses can be 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 method 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) 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, then the server MUST substitute a DAV:propstat element consisting of an empty DAV:prop element and a DAV:status element of value 200 (OK) in its place.

>> Request << ]]>

>> Response << /container/ HTTP/1.1 200 OK HTTP/1.1 404 Not Found ]]>

>> Request << ]]>

>> Response << /container/ HTTP/1.1 200 OK ]]>

>> Request << ]]>

>> Response << /container/ HTTP/1.1 200 OK ]]>

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 a 200 (OK) response with an empty (zero-length) message body instead of a 207 (Multi-Status) response.

>> Request << My Container ]]>

>> Response << /container/ HTTP/1.1 200 OK ]]>

>> Request << My Container ]]>

>> Response <<

When a REPORT method 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, then the server MUST substitute a DAV:propstat element consisting of an empty DAV:prop element and a DAV:status element of value 200 (OK) in its place.

This example uses the CALDAV:calendar-multiget REPORT type.

>> Request << /murch/work/abc.ics /murch/work/qrs.ics /murch/work/xyz.ics ]]>

>> Response << /murch/work/abc.ics "jahsd823ru" HTTP/1.1 200 OK HTTP/1.1 404 Not Found /murch/work/qrs.ics HTTP/1.1 404 Not Found /murch/work/xyz.ics "p08ulkj" HTTP/1.1 200 OK HTTP/1.1 404 Not Found ]]>

This example uses the CALDAV:calendar-multiget REPORT type.

>> Request << /murch/work/abc.ics /murch/work/qrs.ics /murch/work/xyz.ics ]]>

>> Response << /murch/work/abc.ics "jahsd823ru" HTTP/1.1 200 OK /murch/work/qrs.ics HTTP/1.1 404 Not Found /murch/work/xyz.ics "p08ulkj" HTTP/1.1 200 OK ]]>

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.

>> Request << My Container ]]>

>> Response << HTTP/1.1 200 OK ]]>

>> Request << My Container ]]>

>> Response <<

The PUT and POST methods 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. In cases where the client would normally issue a subsquent 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 or POST request. By doing this, the client can coalesce the create/update and retrieve operations into one round-trip rather than two.

>> Request <<

>> Response <<

>> Request <<

>> Response <<

>> Request <<

>> Response <<

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 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.

>> Request << ]]>

>> Response << /murch/ http://example.com/ns/sync/2216-2 HTTP/1.1 200 OK /murch/work/ http://example.com/ns/sync/2136-34 HTTP/1.1 200 OK /murch/home/ http://example.com/ns/sync/2141-19 HTTP/1.1 200 OK ]]>

>> Request << ]]>

>> Response << /murch/work/ http://example.com/ns/sync/2136-34 HTTP/1.1 200 OK /murch/home/ http://example.com/ns/sync/2141-19 HTTP/1.1 200 OK ]]>

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 Preferences Registry defined in . Preference: depth-noroot 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. Reference: Notes: 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 author would like to thank the following individuals for contributing their ideas and support for writing this specification: Cyrus Daboo, Helge Hess, Andrew McMillan, and Arnaud Quillaud. 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; &rfc4918; &rfc5689; &rfc5995; &prefer; &part2; &rfc4791; &rfc6578; &rfc6638; Microsoft Developer Network Microsoft Developer Network Microsoft Developer Network Microsoft Developer Network

This 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. Authors are encouraged to implement the Brief header field functionality in conjunction with this specification to further promote interoperability with products that use the Brief header field exclusively.

Have we settled on the proper server behavior when "return-minimal" would result in zero DAV:propstat elements? Are there any other use cases for "return-minimal" and/or "return-representation" that we should document (COPY/MOVE, versioning extensions)?

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 ]]>