MAY"> MUST"> MUST NOT"> NOT RECOMMENDED"> OPTIONAL"> RECOMMENDED"> REQUIRED"> SHALL"> SHALL NOT"> SHOULD"> SHOULD NOT"> ]> greenbytes GmbH

Hafenweg 16 MuensterNW48155 Germany +49 251 2807760 julian.reschke@greenbytes.de http://greenbytes.de/tech/webdav/

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 lead 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. As a matter of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose. On the other hand, WebDAV-based protocols such as the Calendar Extensions to WebDAV (CalDAV) 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. Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject "subscribe" to . Discussions of the WEBDAV working group are archived at . 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 . Umbrella issue for editorial fixes/enhancements. There seems to be some confusion about whether a POST as described here would allow a server to store the resource into a different folder. That is not the intent, e.g., it doesn't change WebDAV's containment model to the one used in AtomPub. Is a clarification needed? Clarify "internal member" by pointing to RFC 4918, Section 3.

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": 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 lead 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. As a matter of fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose (): 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 (): 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. (...) As a matter of fact, 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). Note: the vCard Extensions to WebDAV (CardDAV) () suffer from the same issue, and may be able to take advantage of this specification. This specification defines a discovery mechanism through which servers can advertise support for POST requests with the aforementioned "add collection member" semantics. Note: the author previously proposed a new HTTP method for exactly this purpose (), but quite a few reviewers pointed out that this would duplicate the original semantics of POST. Thus this proposal that avoids adding a new HTTP method is made.

The terminology used here follows that in the WebDAV specification (). 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 uses XML DTD fragments () as a purely notational convention. In particular: Element names use the namespace "http://purl.org/NET/webdav/post#". When an XML element type in this namespace is referenced in this document outside of the context of an XML fragment, the string "p:" will be prefixed to the element name. With sufficient support from the WebDAV WG's former mailing list and/or the IESG Applications Area the property defined later on could potentially be moved into the DAV: namespace. Element ordering is irrelevant. Extension elements/attributes (elements/attributes not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise.

Due to the reasons stated in , clients can not rely on a specific server behavior when POST is applied to a collection. This problem is addressed by this specification by allowing servers to advertise a URI that has the desired "add member" semantics. Note that servers that already use POST for a different purpose can just expose a different URI for that purposeseparate 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 for the definition of "internal member"). It &MUST; identify a resource on the same server as the WebDAV collection (the host and port components () 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 returned on failure. The URI of the newly created resource is returned in the HTTP Location response header (). Note: the fact that a server advertises an "Add-Member" URI does not imply any special semantics of the collection itself. For instance, member URIs assigned by the server are not necessarily unique over time (a member URI may be assigned again to a new resource when it previously was removed). Note: the "Add-Member" URI can be the identical to the collection's URI (in which case the server just advertises the fact that POST to the WebDAV collection's URI is supported as defined within this specification). But it can also be different from it, in which case it doesn't need to have any relation to the collection's URI.

Given a collection URI of /docs/collection/

all of the URIs below might occur as "Add-Member" URIs: /docs/collection/ /docs/collection/;post /docs/collection;post/ /docs/collection/&post /post-service?path=/collection/

The remainder of the document uses the same format just for reasons of consistency; any other HTTP URI on the same server would do as well.

The p:add-member property is defined on WebDAV collections, and contains the "Add-Member" URI for that collection (embedded inside a DAV:href element).

<!ELEMENT p:add-member (href)> <!-- href: defined in -->

A PROPFIND/allprop request &SHOULD-NOT; return this property (see ). Servers &MUST; implement the DAV:supported-live-property-set property defined in , and report the property p:add-member as a supported live property.

>>Request PROPFIND /collection/ HTTP/1.1 Host: example.com Content-Type: application/xml; charset="utf-8" Content-Length: <?xml version="1.0" encoding="utf-8" ?> <propfind xmlns="DAV:" xmlns:p="http://purl.org/NET/webdav/post#"> <prop> <p:add-member/> </prop> </propfind>

>>Response HTTP/1.1 207 Multi-Status Content-Type: application/xml; charset="utf-8" Content-Length: <?xml version="1.0" encoding="utf-8" ?> <multistatus xmlns="DAV:" xmlns:p="http://purl.org/NET/webdav/post#"> <response> <href>/collection/</href> <propstat> <prop> <p:add-member> <href>/collection;add-member/</href> </p:add-member> </prop> <status>HTTP/1.1 200 OK</status> </propstat> </response> </multistatus> Note that in this case, the server has minted a separate URI for the purpose of adding new content.

There may be cases in which it is more efficient to expose the Add-Member URI in HTTP headers or in (X)HTML content. For this use case, this specification defines a new link relation with the name:

http://purl.org/NET/webdav/post#add-member

It can be used both in HTTP Link headers (see ):

>>Request HEAD /collection/ HTTP/1.1 Host: example.com

>>Response HTTP/1.1 200 OK Link: </collection;add-member/>; rel="http://purl.org/NET/webdav/post#add-member"

...and in (X)HTML content:

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> <head> <title>Contents of /collection/</title> <link rel="http://purl.org/NET/webdav/post#add-member" href="/collection;add-member/" /> </head <body>...</body> </html>

In the AtomPub protocol, clients can use the entity header "Slug" to suggest parts of the URI to be created (see ). 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 as by its definition of a generic HTTP header. Servers should process it exactly the way defined by AtomPub.

>>Request POST /collection;add-member/ HTTP/1.1 Host: example.com Content-Type: text/plain Slug: Sample Text Content-Length: Sample text.

>>Response HTTP/1.1 201 Created Location: http://example.com/collection/sample%20text

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 () that can be used to provide the client with additional information about why exactly the request failed.

(p:allow-client-defined-URI): the server allows clients to specify the last path segment for newly created resources. The precondition element &MAY; contain a p: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 p:allow-client-defined-uri (p:add-member?)>

In this example, the client tries to use PUT to create a new internal member of /collection/.

>>Request PUT /collection/new.txt HTTP/1.1 Host: example.com Content-Type: text/plain Content-Length: Sample text.

>>Response HTTP/1.1 405 Method Not Allowed Allow: GET, HEAD, TRACE, PROPFIND, COPY, MOVE Content-Type: application/xml; charset=UTF-8 Content-Length: <error xmlns="DAV:" xmlns:p="http://purl.org/NET/webdav/post#"> <p:allow-client-defined-uri> <p:add-member> <href>/collection;add-member/</href> </p:add-member> </p: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 able add new collection members (). Consistent with that, a server &MUST; reject a POST request to the Add-Member URI of a collection unless the authenticated principal is granted DAV:bind privilege on the associated WebDAV collection resource.

This document does not introduce any new internationalization considerations beyond those discussed in .

This specification does not require any actions from IANA.

All security considerations connected to HTTP/WebDAV and XML apply for this specification as well, namely, and . 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 p: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 not following p:add-member URIs to different servers, and/or verifying that the p:add-member property is indeed a live property (this can be achieved by testing the DAV:supported-live-property-set property, or by checking whether p:add-member is returned upon PROPFIND/allprop)

This document has benefited from thoughtful discussion by Cyrus Daboo and Bernard Desruissaux.

Harvard University

sob@harvard.edu

University of California, Irvine

fielding@ics.uci.edu

W3C

jg@w3.org

Compaq Computer Corporation

mogul@wrl.dec.com

MIT Laboratory for Computer Science

frystyk@w3.org

Xerox Corporation

masinter@parc.xerox.com

Microsoft Corporation

paulle@microsoft.com

W3C

timbl@w3.org

Rational Software

geoffrey.clemm@rational.com

IBM

jamsden@us.ibm.com

IBM

tim_ellison@uk.ibm.com

Microsoft

ckaler@microsoft.com

UC Santa Cruz, Dept. of Computer Science

ejw@cse.ucsc.edu

IBM

20 Maguire Road Lexington MA 02421 geoffrey.clemm@us.ibm.com

greenbytes GmbH

Salzmannstrasse 152 MuensterNW48159 Germany julian.reschke@greenbytes.de

Oracle Corporation

500 Oracle Parkway Redwood Shores CA 94065 eric.sedlar@oracle.com

U.C. Santa Cruz, Dept. of Computer Science

1156 High Street Santa Cruz CA 95064 ejw@cse.ucsc.edu

Textuality and Netscape

tbray@textuality.com

Microsoft

jeanpa@microsoft.com

University of Illinois at Chicago and Text Encoding Initiative

cmsmcq@uic.edu

Sun Microsystems

eve.maler@east.sun.com

francois@yergeau.com

CommerceNet

2064 Edgewood Dr. Palo Alto CA 94303 US ldusseault@commerce.net

mnot@mnot.net

VeriSign, Inc.

shollenbeck@verisign.com

Dover Beach Consulting, Inc.

mrose@dbc.mtview.ca.us

Adobe Systems Incorporated

LMM@acm.org

Apple Inc.

cyrus@daboo.name

Oracle Corporation

bernard.desruisseaux@oracle.com

CommerceNet

ldusseault@commerce.net

Google

joe@bitworking.org

NewBay Software

bill@dehora.net

greenbytes GmbH

julian.reschke@greenbytes.de

Apple Inc.

cyrus@daboo.name

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