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

Network Working Group                                         J. Reschke
Internet-Draft                                                greenbytes
Intended status: Standards Track                            May 21, 2010
Expires: November 22, 2010

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

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

Reschke                 Expires November 22, 2010               [Page 1]
Internet-Draft      POST to add to WebDAV Collections           May 2010

Status of This Memo

   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 on November 22, 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.

Reschke                 Expires November 22, 2010               [Page 2]
Internet-Draft      POST to add to WebDAV Collections           May 2010

Table of Contents

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

Reschke                 Expires November 22, 2010               [Page 3]
Internet-Draft      POST to add to WebDAV Collections           May 2010

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

      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

Reschke                 Expires November 22, 2010               [Page 4]
Internet-Draft      POST to add to WebDAV Collections           May 2010

   or a primary key).

      Note: the vCard Extensions to WebDAV (CardDAV)
      ([draft-ietf-vcarddav-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.

   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]), 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]).

   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.

Reschke                 Expires November 22, 2010               [Page 5]
Internet-Draft      POST to add to WebDAV Collections           May 2010

3.  Protocol Extension

   Due to the reasons stated in Section 1, 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.

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

   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/

Reschke                 Expires November 22, 2010               [Page 6]
Internet-Draft      POST to add to WebDAV Collections           May 2010

      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/

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

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

   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

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

Reschke                 Expires November 22, 2010               [Page 7]
Internet-Draft      POST to add to WebDAV Collections           May 2010

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

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

Reschke                 Expires November 22, 2010               [Page 8]
Internet-Draft      POST to add to WebDAV Collections           May 2010

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], 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 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?)>

Reschke                 Expires November 22, 2010               [Page 9]
Internet-Draft      POST to add to WebDAV Collections           May 2010

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

6.  Internationalization Considerations

   This document does not introduce any new internationalization
   considerations beyond those discussed in Section 20 of [RFC4918].

Reschke                 Expires November 22, 2010              [Page 10]
Internet-Draft      POST to add to WebDAV Collections           May 2010

7.  IANA Considerations

   This specification does not require any actions from IANA.

8.  Security Considerations

   Security considerations applicable to HTTP [RFC2616], WebDAV
   [RFC4918], and XML [XML] apply for this specification as well,
   namely, Section 20 of [RFC4918] and Section 7 of [RFC3470].

   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

   o  not following DAV:add-member URIs to different servers, and/or

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

10.  References

10.1.  Normative References

   [RFC2119]                       Bradner, S., "Key words for use in
                                   RFCs to Indicate Requirement Levels",
                                   BCP 14, RFC 2119, March 1997.

   [RFC2616]                       Fielding, R., Gettys, J., Mogul, J.,
                                   Frystyk, H., Masinter, L., Leach, P.,
                                   and T. Berners-Lee, "Hypertext
                                   Transfer Protocol -- HTTP/1.1",
                                   RFC 2616, June 1999.

   [RFC3253]                       Clemm, G., Amsden, J., Ellison, T.,

Reschke                 Expires November 22, 2010              [Page 11]
Internet-Draft      POST to add to WebDAV Collections           May 2010

                                   Kaler, C., and J. Whitehead,
                                   "Versioning Extensions to WebDAV",
                                   RFC 3253, March 2002.

   [RFC3744]                       Clemm, G., Reschke, J., Sedlar, E.,
                                   and J. Whitehead, "Web Distributed
                                   Authoring and Versioning (WebDAV)
                                   Access Control Protocol", RFC 3744,
                                   May 2004.

   [RFC4918]                       Dusseault, L., Ed., "HTTP Extensions
                                   for Web Distributed Authoring and
                                   Versioning (WebDAV)", RFC 4918,
                                   June 2007.

   [XML]                           Bray, T., Paoli, J., Sperberg-
                                   McQueen, C., Maler, E., and F.
                                   Yergeau, "Extensible Markup Language
                                   (XML) 1.0 (Fifth Edition)", W3C REC-
                                   xml-20081126, November 2008, <http://
                                   www.w3.org/TR/2008/
                                   REC-xml-20081126/>.

10.2.  Informative References

   [RFC3470]                       Hollenbeck, S., Rose, M., and L.
                                   Masinter, "Guidelines for the Use of
                                   Extensible Markup Language (XML)
                                   within IETF Protocols", RFC 3470,
                                   BCP 70, January 2003.

   [RFC4791]                       Daboo, C., Desruisseaux, B., and L.
                                   Dusseault, "Calendaring Extensions to
                                   WebDAV (CalDAV)", RFC 4791,
                                   March 2007.

   [RFC5023]                       Gregorio, J. and B. de hOra, "The
                                   Atom Publishing Protocol", RFC 5023,
                                   October 2007.

   [draft-ietf-vcarddav-carddav]   Daboo, C., "vCard Extensions to
                                   WebDAV (CardDAV)",
                                   draft-ietf-vcarddav-carddav-10 (work
                                   in progress), November 2009.

   [draft-reschke-http-addmember]  Reschke, J., "The HTTP ADDMEMBER
                                   Method",
                                   draft-reschke-http-addmember-00 (work

Reschke                 Expires November 22, 2010              [Page 12]
Internet-Draft      POST to add to WebDAV Collections           May 2010

                                   in progress), February 2005.

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

A.6.  since draft-reschke-webdav-post-05

   Close issue "collection" (not making the addition).

A.7.  since draft-reschke-webdav-post-06

   None yet.

A.8.  since draft-reschke-webdav-post-07

   Editorial improvements.

Reschke                 Expires November 22, 2010              [Page 13]
Internet-Draft      POST to add to WebDAV Collections           May 2010

Appendix B.  Resolved issues (to be removed by RFC Editor before
             publication)

   Issues that were either rejected or resolved in this version of this
   document.

B.1.  edit

   Type: edit

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

Index

   A
      Add-Member URI  6

   C
      Condition Names
         DAV:allow-client-defined-URI (pre)  9
      COPY method
         Additional Preconditions  9

   D
      DAV:allow-client-defined-URI  9

   L
      LOCK method
         Additional Preconditions  9

   M
      MKCOL method
         Additional Preconditions  9
      MOVE method
         Additional Preconditions  9

   P
      PUT method
         Additional Preconditions  9

Reschke                 Expires November 22, 2010              [Page 14]
Internet-Draft      POST to add to WebDAV Collections           May 2010

Author's Address

   Julian F. Reschke
   greenbytes GmbH
   Hafenweg 16
   Muenster, NW  48155
   Germany

   Phone: +49 251 2807760
   EMail: julian.reschke@greenbytes.de
   URI:   http://greenbytes.de/tech/webdav/

Reschke                 Expires November 22, 2010              [Page 15]