Internet Engineering Task Force (IETF) J. Reschke
Request for Comments: 5995 greenbytes
Category: Standards Track September 2010
ISSN: 2070-1721
Using POST to Add Members to Web Distributed Authoring and Versioning
(WebDAV) Collections
Abstract
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, such as the
Calendaring 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.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc5995.
Reschke Standards Track [Page 1]
RFC 5995 POST to Add to WebDAV Collections September 2010
Copyright Notice
Copyright (c) 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.
Table of Contents
1. Introduction ....................................................2
2. Terminology .....................................................4
3. Protocol Extension ..............................................4
3.1. Definition of "Add-Member" URI .............................5
3.2. Discovery ..................................................6
3.2.1. DAV:add-member Property (Protected) .................6
3.2.2. Example .............................................6
3.3. Relation to AtomPub's "Slug" Header Field ..................7
3.4. Example Operation ..........................................7
4. Additional Semantics for Existing Methods .......................8
4.1. Additional Preconditions ...................................8
4.2. Example: Failed PUT Request ................................8
5. Relationship to WebDAV Access Control Protocol ..................9
6. Internationalization Considerations .............................9
7. Security Considerations .........................................9
8. Acknowledgements ...............................................10
9. References .....................................................10
9.1. Normative References ......................................10
9.2. Informative References ....................................11
Index .............................................................11
1. Introduction
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":
Reschke Standards Track [Page 2]
RFC 5995 POST to Add to WebDAV Collections September 2010
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
Universally Unique Identifier (UUID) or a primary key).
Note: The vCard Extensions to WebDAV (CardDAV) ([CARDDAV]) suffer
from the same issue, and may be able to take advantage of this
specification.
Reschke Standards Track [Page 3]
RFC 5995 POST to Add to WebDAV Collections September 2010
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 addresses the use case of
creating new non-collection resources. It was not a goal for this
specification 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 ([ADDMEMBER]), but quite a few reviewers pointed out
that this would duplicate the original semantics of POST. Thus,
this proposal, which avoids adding a new HTTP method, is made.
2. Terminology
The terminology used here follows that in the WebDAV specification
([RFC4918]).
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 [RFC2119].
This document uses XML DTD fragments ([XML]) as a purely notational
convention. In particular:
o Element ordering is irrelevant.
o 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 ([RFC4918], 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.
3. Protocol Extension
Due to the reasons stated in Section 1, clients cannot 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.
Reschke Standards Track [Page 4]
RFC 5995 POST to Add to WebDAV Collections September 2010
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.
3.1. Definition of "Add-Member" URI
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 preconditions related to creating a resource in the
collection using a PUT request, then those same preconditions apply
to the new POST request behavior, and the same HTTP response body
will be returned on failure.
The URI of the newly created resource is returned in the HTTP
Location response header field ([RFC2616], 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 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/
any 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/
Reschke Standards Track [Page 5]
RFC 5995 POST to Add to WebDAV Collections September 2010
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.
3.2. Discovery
3.2.1. DAV:add-member Property (Protected)
DAV:add-member is a protected property (see [RFC4918], 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
[RFC4918], Section 9.1). Servers MUST implement the DAV:supported-
live-property-set property defined in Section 3.1.4 of [RFC3253], and
report the property DAV:add-member as a supported live property.
3.2.2. Example
>>Request
PROPFIND /collection/ HTTP/1.1
Host: example.com
Content-Type: application/xml; charset="utf-8"
Content-Length: 118
-- Leo's gemini proxy
-- Connecting to gemini.bortzmeyer.org:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/plain
-- Response ended
-- Page fetched on Mon May 6 19:26:25 2024