Note: a later version of this document has been published as RFC 5995.
The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed Authoring and Versioning (WebDAV) do not define the behavior for the "POST" method when applied to collections, as the base specification (HTTP) leaves implementers lots of freedom for the semantics of "POST".
This has led to a situation where many WebDAV servers do not implement POST for collections at all, although it is well suited to be used for the purpose of adding new members to a collection, where the server remains in control of the newly assigned URL. In fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose. On the other hand, WebDAV-based protocols↑ I ↓ such as the Calendar↑ I ↓ Extensions to WebDAV (CalDAV)↑ I ↓ frequently require clients to pick a unique URL, although the server could easily perform that task.
This specification defines a discovery mechanism through which servers can advertise support for POST requests with the aforementioned "add collection member" semantics.
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 in February 2011.
Copyright © 2010 IETF Trust and the persons identified as the document authors. All rights reserved.
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.
Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at <mailto:email@example.com>, which may be joined by sending a message with subject "subscribe" to <mailto:firstname.lastname@example.org>. Discussions of the WEBDAV working group are archived at <http://lists.w3.org/Archives/Public/w3c-dist-auth/>.
Note that although discussion takes place on the WebDAV working group's mailing list, this is not a working group document.
XML versions, latest edits and the issues list for this document are available from <http://greenbytes.de/tech/webdav/#draft-reschke-webdav-post>.
|I auth48 (type: edit, status: closed)|
|email@example.com||2010-08-31||Umbrella issue for changes made during the RFC Editor's AUTH48 period.|
|Associated changes in this document: <#rfc.change.auth48.1>, <#rfc.change.auth48.2>, <#rfc.change.auth48.3>, <#rfc.change.auth48.4>, <#rfc.change.auth48.5>, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 3, 3.1, 3.1, 3.1, 3.1, 3.3, 4, 4, 4, 4, 5, 5, 6, <#rfc.change.auth48.32>, 7, 9.1, 9.2, 9.2, 9.2, 9.2, <#rfc.change.auth48.39>, del-10.|
The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed Authoring and Versioning (WebDAV) ([RFC4918], Section 9.5) do not define the behavior for the "POST" method when applied to collections, as the base specification (HTTP) leaves implementers lots of freedom for the semantics of "POST":¶
9.5 POST for Collections
Since by definition the actual function performed by POST is determined by the server and often depends on the particular resource, the behavior of POST when applied to collections cannot be meaningfully modified because it is largely undefined. Thus, the semantics of POST are unmodified when applied to a collection.
This has led to a situation where many WebDAV servers do not implement POST for collections at all, although it is well suited to be used for the purpose of adding new members to a collection, where the server remains in control of the newly assigned URL. In fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose ([RFC5023], Section 9.2):¶
9.2 Creating Resources with POST
To add members to a Collection, clients send POST requests to the URI of the Collection.
On the other hand, WebDAV-based protocols↑↓ such as Calendaring Extensions to WebDAV (CalDAV)↑↓ frequently require clients to pick a unique URL, although the server could easily perform that task ([RFC4791], Section 5.3.2):¶
5.3.2 Creating Calendar Object Resources
When servers create new resources, it's not hard for the server to choose an unmapped URI. It's slightly tougher for clients, because a client might not want to examine all resources in the collection and might not want to lock the entire collection to ensure that a new resource isn't created with a name collision. (...)
Letting the server choose the member URI not only is a simplification for certain types of clients, but can also reduce the complexity of the server (in that it doesn't need to persist an additional client-supplied identifier where it already has an internal one like a ↑↓
UUID or a primary key).¶
This specification defines a discovery mechanism through which servers can advertise support for POST requests with the aforementioned "add collection member" semantics.¶
This specification deliberately only ad↑↓resses the use case of creating new non-collection resources↑↓
, and that it was not a goal to supply the same functionality for creating collection resources (MKCOL)↑↓ , or for other operations that require the client to specify a new URL (LOCK, MOVE, or COPY).¶
Due to the reasons stated in Section 1, clients can↑↓
Servers that already use POST for a different purpose can just expose a separate URI. Other servers can just advertise the collection's own URI, thus avoiding minting another URI for a limited purpose.¶
The "Add-Member" URI of a WebDAV collection is a URI that will accept HTTP POST requests, and will interpret these as requests to store the enclosed entity as a new internal member of the collection (see Section 3 of [RFC4918] for the definition of "internal member"). It MUST identify a resource on the same server as the WebDAV collection (the host and port components ([RFC2616], Section 3.2.2) of the URIs must match).¶
If there are pre↑↓
-conditions related to creating a resource in the collection using a PUT request, then those same pre↑↓ -conditions apply to the new POST request behavior, and the same HTTP response body will be returned on failure.¶
PROPFIND /collection/ HTTP/1.1 Host: example.com Content-Type: application/xml; charset="utf-8" Content-Length: 118 <?xml version="1.0" encoding="utf-8" ?> <propfind xmlns="DAV:"> <prop> <add-member/> </prop> </propfind>
HTTP/1.1 207 Multi-Status Content-Type: application/xml; charset="utf-8" Content-Length: 340 <?xml version="1.0" encoding="utf-8" ?> <multistatus xmlns="DAV:"> <response> <href>/collection/</href> <propstat> <prop> <add-member> <href>/collection;add-member/</href> </add-member> </prop> <status>HTTP/1.1 200 OK</status> </propstat> </response> </multistatus>
In this case, the server has minted a separate URI for the purpose of adding new content.
In the AtomPub protocol, clients can use the entity header field "Slug" to suggest parts of the URI to be created (see [RFC5023], Section 9.7). Note that servers are free to ignore this suggestion, or to use whatever algorithm ↑↓
that makes sense to generate the new URI.¶
The same applies to the extension defined here: clients can use the "Slug" header field, as by definition it is a generic HTTP header field. Servers should process it exactly in the way defined by AtomPub.¶
POST /collection;add-member/ HTTP/1.1 Host: example.com Content-Type: text/plain Slug: Sample Title Content-Length: 12 Sample text.
HTTP/1.1 201 Created Location: http://example.com/collection/sample%20title
One important use case for this specification ↑↓
are collections that act as WebDAV collections for the purpose of read access (PROPFIND Depth 1/Infinity), but which only support internal member URIs assigned by the server. These collections will not allow a client to create a new member using methods like PUT, MKCOL, LOCK, COPY↑↓ or MOVE. Therefore, this specification defines a new precondition name ([RFC4918], Section 16) that can be used to provide the client with additional information ↑↓ about why exactly the request failed.¶
(DAV:allow-client-defined-URI): the server allows clients to specify the last path segment for newly created resources.¶
The precondition element MAY contain an add-member-uri XML element specifying the "Add-Member" URI associated with the collection, on which the creation of a new child resource was attempted:¶
<!ELEMENT allow-client-defined-uri (add-member?)>
In this example, the client tries to use PUT to create a new internal member of /collection/.¶
PUT /collection/new.txt HTTP/1.1 Host: example.com Content-Type: text/plain Content-Length: 12 Sample text.
HTTP/1.1 405 Method Not Allowed Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE Content-Type: application/xml; charset=UTF-8 Content-Length: 172 <error xmlns="DAV:"> <allow-client-defined-uri> <add-member> <href>/collection;add-member/</href> </add-member> </allow-client-defined-uri> </error>
The request fails with a 405 (Method Not Allowed) status, but also provides the reason, and a pointer to the "Add-Member" URI in the response body.¶
The WebDAV ↑↓
ACL specification requires the DAV:bind privilege to be granted on a collection for the client to be able to add new collection members ([RFC3744], Section 3.9). Consistent with that, a server MUST reject a POST request to the Add-Member URI of a collection↑↓ unless the principal executing the request is granted DAV:bind privilege on the associated WebDAV collection resource.¶
This specification does not require any actions from IANA.
Furthermore, servers should be aware that deriving the member path from the data being stored in the resource could potentially expose confidential information. This could even be the case when only a hash code of the content is used.¶
In addition, on servers that do not support this specification, a malevolent user could set the DAV:add-member URI as a custom property, tricking other users to post content to an entirely different URI. Clients can protect themselves against this scenario by ¶
This document has benefited from thoughtful discussion by Cyrus Daboo and Bernard Desruisseaux.¶
Added and resolved issues "acl", "forbidden-put", "member-uri-content", "post-error-semantics", "property-trust", "rational-server-uri", ""remote-uri", "uri-format" and "uri-uniqueness".
Add and resolve issue "containment".
Update draft-ietf-vcarddav-carddav reference.
Update XML, draft-ietf-vcarddav-carddav and draft-nottingham-http-link-header references.
Add and resolve issues "link-header" and "ns".
Add and resolve issues "put-only" and "protected".
Update vcarddav reference. In the example, do not use the same content for Slug header field and request body. Add issue "collection".
Close issue "collection" (not making the addition).