Using POST to Add Members to Web Distributed Authoring and Versioning (WebDAV) Collections
Extracted elements (16)
Letting the server assign the new member URI simplifies clients (no need to enumerate existing members or lock the collection to avoid name collisions) and can reduce server complexity by reusing internal identifiers such as UUIDs or primary keys rather than persisting a separate client-supplied identifier.
The specification uses POST rather than introducing a new HTTP method (previously proposed as ADDMEMBER) because POST's original semantics already cover the use case of adding a member to a collection. Reviewers pointed out that a new method would duplicate existing POST semantics, so this approach avoids HTTP method proliferation.
This specification deliberately limits its scope to creating new non-collection resources only; creating collections (MKCOL), or operations that require client-specified URLs (LOCK, MOVE, COPY), are explicitly out of scope.
CalDAV (RFC 4791) and CardDAV require clients to pick unique member URIs, creating collision and locking complexity. This specification provides a mechanism those protocols (and similar WebDAV-based protocols) can adopt so that the server assigns URIs instead.
Clients MAY use the AtomPub 'Slug' header field to suggest a portion of the new resource's URI when POSTing to the Add-Member URI. Servers should process it exactly as defined by AtomPub (RFC 5023 Section 9.7), but are free to ignore the suggestion.
A PROPFIND/allprop request SHOULD NOT return the DAV:add-member property. Servers MUST implement DAV:supported-live-property-set (RFC 3253 Section 3.1.4) and report DAV:add-member as a supported live property.
A server MUST reject a POST request to the Add-Member URI unless the principal executing the request has been granted the DAV:bind privilege on the associated WebDAV collection resource, consistent with RFC 3744 Section 3.9.
If preconditions apply to PUT-based creation in the collection, those same preconditions apply to the POST-based Add-Member request, and the same HTTP response body is returned on failure.
The Add-Member URI MUST identify a resource on the same server as the WebDAV collection; specifically, the host and port components of the Add-Member URI and the collection URI must match.
The DAV:allow-client-defined-URI precondition element MAY contain an add-member-uri XML element specifying the Add-Member URI for the collection on which resource creation was attempted, enabling clients to retry using the correct URI.
The URI of the newly created resource MUST be returned in the HTTP Location response header field upon a successful POST to the Add-Member URI.
DAV:add-member is a protected live property defined on WebDAV collections, containing the Add-Member URI embedded inside a DAV:href element. Its XML content model is: <!ELEMENT add-member (href)>.
DAV:allow-client-defined-URI is a new precondition name that servers use to inform clients that the collection does not allow client-specified URIs for new members. Its XML content model is: <!ELEMENT allow-client-defined-uri (add-member?)>, optionally embedding the Add-Member URI.
The 'Add-Member' URI is a URI advertised by a WebDAV server that accepts HTTP POST requests and interprets them as requests to store the enclosed entity as a new internal member of the associated collection. The server assigns the new member's URI, which is returned in the HTTP Location response header.
On servers that do not implement this specification, a malicious user could set DAV:add-member as a custom (dead) property, tricking other users into POSTing content to an unintended URI. Clients can mitigate this by refusing to follow Add-Member URIs to different servers, and/or by verifying that DAV:add-member is a live property via DAV:supported-live-property-set or PROPFIND/allprop.
Servers should be aware that deriving the new member's path from the content being stored (including hash codes) could potentially expose confidential information about the stored data.