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

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of 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 March 26, 2009.

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

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.

Table of Contents

1.  Introduction
2.  Terminology
3.  Protocol Extension
    3.1.  Definition of 'Add-Member' URI
    3.2.  Discovery
        3.2.1.  p:add-member Property
        3.2.2.  Example
        3.2.3.  add-member Link Relation
    3.3.  Relation to AtomPub's 'Slug' Header
    3.4.  Example Operation
4.  Internationalization Considerations
5.  IANA Considerations
6.  Security Considerations
7.  References
    7.1.  Normative References
    7.2.  Informative References
§  Index
§  Author's Address
§  Intellectual Property and Copyright Statements

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

Note: the vCard Extensions to WebDAV (CardDAV) ([draft‑ietf‑vcarddav‑carddav] (Daboo, C., “vCard Extensions to WebDAV (CardDAV),” July 2008.)) 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 ([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.

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 (Fourth Edition),” August 2006.)) 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. [ns] (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.

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 ervers that already use POST for a different purpose can just expose a different URI for that purpose. Other servers can just advertise the collection's own URI, thus avoiding to mint 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. The URI of the newly created resource is returned in the HTTP Location response header ([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).

3.2.  Discovery

3.2.1.  p:add-member Property

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

3.2.2.  Example

>>Request

PROPFIND /collection/ HTTP/1.1
Host: example.com
Content-Type: application/xml; charset="utf-8"
Content-Lenght: 163

<?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: 385

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

3.2.3.  add-member Link Relation

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 uses both in HTTP Link headers (see [draft‑nottingham‑http‑link‑header] (Nottingham, M., “HTTP Header Linking,” July 2008.)):

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

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>

3.3.  Relation to AtomPub's 'Slug' Header

In the AtomPub protocol, clients can use the entity header "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 as by its definition of a generic HTTP header. Servers should process it exactly 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 Text
Content-Lenght: 12

Sample text.

>>Response

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

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

5.  IANA Considerations

This specification does not require any actions from IANA.

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

7.  References

7.1. Normative References

7.2. Informative References

Index

Author's Address

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.