Using POST to add Members to Web Distributed Authoring and Versioning (WebDAV) Collections
draft-reschke-webdav-post-05

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

Editorial Note (To be removed by RFC Editor before publication)

Please send comments to the Distributed Authoring and Versioning (WebDAV) working group at mailto:w3c-dist-auth@w3.org, which may be joined by sending a message with subject "subscribe" to mailto:w3c-dist-auth-request@w3.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.

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

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.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on May 26, 2010.

Copyright Notice

Copyright (c) 2009 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 BSD License.

Table of Contents

1.  Introduction
2.  Terminology
3.  Protocol Extension
    3.1.  Definition of 'Add-Member' URI
    3.2.  Discovery
        3.2.1.  DAV:add-member Property (protected)
        3.2.2.  Example
    3.3.  Relation to AtomPub's 'Slug' Header Field
    3.4.  Example Operation
4.  Additional Semantics for existing Methods
    4.1.  Additional Preconditions
    4.2.  Example: Failed PUT Request
5.  Relationship to WebDAV Access Control Protocol
6.  Internationalization Considerations
7.  IANA Considerations
8.  Security Considerations
9.  Acknowledgements
10.  References
    10.1.  Normative References
    10.2.  Informative References
Appendix A.  Change Log (to be removed by RFC Editor before publication)
    A.1.  since draft-reschke-webdav-post-00
    A.2.  since draft-reschke-webdav-post-01
    A.3.  since draft-reschke-webdav-post-02
    A.4.  since draft-reschke-webdav-post-03
    A.5.  since draft-reschke-webdav-post-04
Appendix B.  Open issues (to be removed by RFC Editor prior to publication)
    B.1.  edit
    B.2.  collection
§  Index
§  Author's Address

1.  Introduction

The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed Authoring and Versioning (WebDAV) ([RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), 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 ([RFC5023] (Gregorio, J. and B. de hOra, “The Atom Publishing Protocol,” October 2007.), 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] (Daboo, C., Desruisseaux, B., and L. Dusseault, “Calendaring Extensions to WebDAV (CalDAV),” March 2007.), 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) ([draft‑ietf‑vcarddav‑carddav] (Daboo, C., “vCard Extensions to WebDAV (CardDAV),” November 2009.)) 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 ([draft‑reschke‑http‑addmember] (Reschke, J., “The HTTP ADDMEMBER Method,” February 2005.)), 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.

2.  Terminology

The terminology used here follows that in the WebDAV specification ([RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.)).

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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

This document uses XML DTD fragments ([XML] (Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, “Extensible Markup Language (XML) 1.0 (Fifth Edition),” November 2008.)) 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 ([RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), 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 (Introduction), 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.

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] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.) 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] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.), 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 field ([RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.), 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

   /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.

3.2.  Discovery

3.2.1.  DAV:add-member Property (protected)

DAV:add-member is a protected property (see [RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), Section 15) defined on WebDAV collections, and contains the "Add-Member" URI for that collection (embedded inside a DAV:href element).

<!ELEMENT add-member (href)>
<!-- href: defined in [RFC4918], Section 14.7 -->

A PROPFIND/allprop request SHOULD NOT return this property (see [RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), Section 9.1). Servers MUST implement the DAV:supported-live-property-set property defined in Section 3.1.4 of [RFC3253] (Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, “Versioning Extensions to WebDAV,” March 2002.), 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

<?xml version="1.0" encoding="utf-8" ?>
<propfind xmlns="DAV:">
  <prop>
    <add-member/>
  </prop>
</propfind>

>>Response

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>

Note that in this case, the server has minted a separate URI for the purpose of adding new content.

3.3.  Relation to AtomPub's 'Slug' Header Field

In the AtomPub protocol, clients can use the entity header field "Slug" to suggest parts of the URI to be created (see [RFC5023] (Gregorio, J. and B. de hOra, “The Atom Publishing Protocol,” October 2007.), 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 its definition of a generic HTTP header field. Servers should process it exactly in the way defined by AtomPub.

3.4.  Example Operation

>>Request

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

Sample text.

>>Response

HTTP/1.1 201 Created
Location: http://example.com/collection/sample%20title

4.  Additional Semantics for existing Methods

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] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), 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.

4.1.  Additional Preconditions

(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:

<!ELEMENT allow-client-defined-uri (add-member?)>

4.2.  Example: Failed PUT Request

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: 12

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: 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.

5.  Relationship to WebDAV Access Control Protocol

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 ([RFC3744] (Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, “Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol,” May 2004.), 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.

6.  Internationalization Considerations

This document does not introduce any new internationalization considerations beyond those discussed in Section 20 of [RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.).

7.  IANA Considerations

This specification does not require any actions from IANA.

8.  Security Considerations

All security considerations connected to HTTP/WebDAV and XML apply for this specification as well, namely, [RFC4918] (Dusseault, L., Ed., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.) (Section 20) and [RFC3470] (Hollenbeck, S., Rose, M., and L. Masinter, “Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols,” January 2003.) (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/or
• verifying 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)

9.  Acknowledgements

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

10.  References

10.1. Normative References

10.2. Informative References

Appendix A.  Change Log (to be removed by RFC Editor before publication)

A.1.  since draft-reschke-webdav-post-00

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".

A.2.  since draft-reschke-webdav-post-01

Add and resolve issue "containment".

Update draft-ietf-vcarddav-carddav reference.

A.3.  since draft-reschke-webdav-post-02

Update XML, draft-ietf-vcarddav-carddav and draft-nottingham-http-link-header references.

Add and resolve issues "link-header" and "ns".

A.4.  since draft-reschke-webdav-post-03

Add and resolve issues "put-only" and "protected".

A.5.  since draft-reschke-webdav-post-04

Update vcarddav reference. In the example, do not use the same content for Slug header field and request body. Add issue "collection".

Appendix B.  Open issues (to be removed by RFC Editor prior to publication)

B.1.  edit

Type: edit

julian.reschke@greenbytes.de (2008-09-22): Umbrella issue for editorial fixes/enhancements.

B.2.  collection

Type: change

cyrus@daboo.name (2009-11-05): I have heard from some implementors that they would like collection creation to also be part of this draft. In particular, CalDAV and/or CardDAV clients creating calendars or address books would prefer to leave specification of the resource name to the client.
Proposal:
- Add a DAV:add-collection property containing a URI (which must be different than DAV:add-member)
- A POST on that URI creates a collection within the parent collection, with a server chosen resource name
- If the POST contains an XML body with DAV:mkcol as the root element, then that body is interpreted the same way as MKCOL ext.

Index

Author's Address