Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV)
updates
- rfc-7240 — Prefer Header for HTTP
Extracted elements (18)
The requirement that a minimal MKCALENDAR/MKCOL success response have an empty body is based on two constraints: RFC 4791 requires any successful body to be a CALDAV:mkcalendar-response XML element, and RFC 5689 states that an empty body with a success status implies all properties were set, making a non-empty body ambiguous.
The 'return=representation' preference on state-changing requests provides atomicity: by returning the server's current representation in the response, the client can know any changes were produced by the server rather than a concurrent client, eliminating the need for a subsequent GET request.
This document is based on the Microsoft 'Brief' and extended 'Depth' header fields. The behaviors in Sections 2.1 and 2.2 are identical to those of the Brief header field with PROPFIND and PROPPATCH; Section 4 behavior matches the '1,noroot' and 'infinity,noroot' Depth values. If a server receives both Brief and Prefer headers, clients can expect the server to ignore Brief and use only Prefer.
If omitting 404 DAV:propstat elements would result in a DAV:response containing zero DAV:propstat elements, the server MUST substitute either a DAV:propstat with empty DAV:prop and 200 OK status, or a DAV:status element of value 200 OK.
The 'depth-noroot' preference is only intended to be used with HTTP methods whose definitions explicitly provide support for the Depth header field, and only applies when Depth 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.
When a conditional state-changing request contains '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.
When a MKCALENDAR or extended MKCOL request contains 'return=minimal' and the collection is created with all requested properties set successfully, the server SHOULD return a 201 (Created) response with an empty (zero-length) message body.
When a PROPFIND or REPORT request contains 'return=minimal', the server SHOULD omit all DAV:propstat XML elements containing a DAV:status of 404 (Not Found) from the 207 Multi-Status response.
When a PROPPATCH request contains 'return=minimal' and all instructions are processed successfully, the server SHOULD return 204 (No Content) or 200 (OK) with zero-length body rather than a 207 Multi-Status response.
When a state-changing request (PUT, COPY/MOVE, PATCH, POST) contains 'return=representation' and the resource is created or updated successfully, the server SHOULD include an entity representing the current state of the resource in the 201 or 200 response.
The 'depth-noroot' preference indicates the client wishes the server to exclude the target (root) resource from processing and only apply the HTTP method to the target resource's subordinate resources. It is only applicable when Depth header has value '1' or 'infinity'.
The 'return=minimal' preference from RFC 7240 is given precise WebDAV semantics: for PROPFIND/REPORT it means omit 404 propstat elements; for PROPPATCH it means return 200/204 instead of 207; for MKCALENDAR/MKCOL it means return 201 with empty body on success.
The 'return=representation' preference from RFC 7240 is extended to apply to 412 (Precondition Failed) responses in addition to 2xx responses, enabling clients to retrieve the current resource state without a separate GET when a conditional update fails.
The 'depth-noroot' preference has been added to the HTTP Preferences Registry defined in Section 5.1 of RFC 7240, with a reference to RFC 8144, Section 4.
The HTTP Method Registry references for MKCALENDAR, MKCOL, PROPFIND, PROPPATCH, and REPORT have been updated to include RFC 8144 as an additional reference alongside their existing RFC citations.
The HTTP Status Codes registry entry for status code 412 (Precondition Failed) has been updated to include RFC 8144, Section 3.2 as an additional reference alongside RFC 7232.
No new security considerations are introduced by use of the Prefer header field with WebDAV requests, beyond those discussed in RFC 7240 and those already inherent in those WebDAV requests.