Using POST to add Members to Web Distributed Authoring and Versioning (WebDAV) Collectionsgreenbytes GmbHHafenweg 16MuensterNW48155Germany+49 251 2807760julian.reschke@greenbytes.dehttp://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 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. 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 .
The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed
Authoring and Versioning (WebDAV) (, 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. As a matter of fact,
the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose
(, 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 (, 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. (...)
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 that this specification deliberately only adresses 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).
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 ordering is irrelevant.Extension elements/attributes (elements/attributes not already defined
as valid child elements) may be added anywhere, except when explicitly
stated otherwise.
Note: this specification defines new properties and precondition
names in the "DAV:" namespace, which the WebDAV specification reserves for
use by the IETF (, Section 21.1). However,
there was rough consensus in the WebDAV community that the specification is
of general applicability to other WebDAV related standards efforts, and thus
deserves inclusion into the base namespace.
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 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 for the definition of "internal
member").
It MUST identify a resource on the same server as the WebDAV collection
(the host and port components (, 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 returned on failure.
The URI of the newly created resource is returned in the HTTP Location
response header (, Section 14.30).
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 all of the URIs below might occur as "Add-Member" URIs:
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.
DAV:add-member is a protected property (see , Section 15) defined on WebDAV collections, and
contains the "Add-Member" URI for that collection (embedded inside
a DAV:href element).
]]>
A PROPFIND/allprop request SHOULD NOT return this property (see
, Section 9.1). Servers
MUST implement the DAV:supported-live-property-set property defined
in Section 3.1.4 of , and report the property
DAV:add-member as a supported live property.
>>Request
]]>>>Response/collection//collection;add-member/HTTP/1.1 200 OK
]]>
Note that 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 "Slug" to
suggest parts of the URI to be created (see , 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 as by its definition of a generic HTTP header. Servers should
process it exactly the way defined by AtomPub.
>>Request>>Response
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 (, Section 16)
that can be used to provide the client with additional information about
why exactly the request failed.
Note: although the precondition defined below can be used for
methods other than PUT, the "Add-Member" mechanism defined by this
specification deliberately is restricted to PUT.
(DAV:allow-client-defined-URI): the server allows clients to specify
the last path segment for newly created resources.
The precondition element MAY contain a 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:
]]>
In this example, the client tries to use PUT to create a new internal
member of /collection/.
>>Request>>Response/collection;add-member/
]]>
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 add new collection members (, 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 document does not introduce any new internationalization considerations
beyond those discussed in Section 20 of .
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, (Section 20)
and (Section 7).
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
not following DAV:add-member URIs to different servers, and/orverifying that the DAV: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 DAV:add-member is returned upon PROPFIND/allprop)
This document has benefited from thoughtful discussion by Cyrus Daboo and
Bernard Desruissaux.
Key words for use in RFCs to Indicate Requirement LevelsHarvard Universitysob@harvard.eduHypertext Transfer Protocol -- HTTP/1.1University of California, Irvinefielding@ics.uci.eduW3Cjg@w3.orgCompaq Computer Corporationmogul@wrl.dec.comMIT Laboratory for Computer Sciencefrystyk@w3.orgXerox Corporationmasinter@parc.xerox.comMicrosoft Corporationpaulle@microsoft.comW3Ctimbl@w3.orgVersioning Extensions to WebDAVRational Softwaregeoffrey.clemm@rational.comIBMjamsden@us.ibm.comIBMtim_ellison@uk.ibm.comMicrosoftckaler@microsoft.comUC Santa Cruz, Dept. of Computer Scienceejw@cse.ucsc.eduWeb Distributed Authoring and Versioning (WebDAV) Access Control ProtocolIBM20 Maguire RoadLexingtonMA02421geoffrey.clemm@us.ibm.comgreenbytes GmbHSalzmannstrasse 152MuensterNW48159Germanyjulian.reschke@greenbytes.deOracle Corporation500 Oracle ParkwayRedwood ShoresCA94065eric.sedlar@oracle.comU.C. Santa Cruz, Dept. of Computer Science1156 High StreetSanta CruzCA95064ejw@cse.ucsc.eduExtensible Markup Language (XML) 1.0 (Fifth Edition)Textuality and Netscapetbray@textuality.comMicrosoftjeanpa@microsoft.comUniversity of Illinois at Chicago and Text Encoding Initiativecmsmcq@uic.eduSun Microsystemseve.maler@east.sun.comfrancois@yergeau.comHTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)CommerceNet2064 Edgewood Dr.Palo AltoCA94303USldusseault@commerce.net
Guidelines for the Use of Extensible Markup Language (XML) within IETF ProtocolsVeriSign, Inc.shollenbeck@verisign.comDover Beach Consulting, Inc.mrose@dbc.mtview.ca.usAdobe Systems IncorporatedLMM@acm.orgCalendaring Extensions to WebDAV (CalDAV)Apple Inc.cyrus@daboo.nameOracle Corporationbernard.desruisseaux@oracle.comCommerceNetldusseault@commerce.netThe Atom Publishing ProtocolGooglejoe@bitworking.orgNewBay Softwarebill@dehora.netThe HTTP ADDMEMBER Methodgreenbytes GmbHjulian.reschke@greenbytes.devCard Extensions to WebDAV (CardDAV)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.
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".
Issues that were either rejected or resolved in this version of this
document.
Type: changejulian.reschke@greenbytes.de (2009-01-08):
State that the property is protected.
Resolution:
Done.
Type: editjulian.reschke@greenbytes.de (2009-01-08):
Clarify that this is only for PUT-to-create, not COPY/MOVE/LOCK/MKCOL.
Type: editjulian.reschke@greenbytes.de (2008-09-22):
Umbrella issue for editorial fixes/enhancements.