Network Working Group J. Reschke Internet-Draft greenbytes Expires: August 17, 2005 February 13, 2005 The HTTP ADDMEMBER Method draft-reschke-http-addmember-00 Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. 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 become aware will be disclosed, in accordance with RFC 3668. 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 August 17, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract Frequently, servers may want to allow resource creation through HTTP, but are not able to support HTTP's PUT method for creating new resources, as resource names are completely controlled by the server. This document proposes a new HTTP method called "ADDMEMBER" with semantics similar to those of PUT, except for the fact that the server chooses the URI for the newly created resource. Reschke Expires August 17, 2005 [Page 1]
Internet-Draft The HTTP ADDMEMBER Method February 2005 Editorial Note Distribution of this document is unlimited. Please send comments to the Hypertext Transfer Protocol (HTTP) mailing list at ietf-http-wg@w3.org [1], which may be joined by sending a message with subject "subscribe" to ietf-http-wg-request@w3.org [2]. Discussions of the HTTP working group are archived at <http://lists.w3.org/Archives/Public/ietf-http-wg/>. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 3. ADDMEMBER method . . . . . . . . . . . . . . . . . . . . . . . 3 3.1 Example: ADDMEMBER . . . . . . . . . . . . . . . . . . . . 4 4. Feature Discovery . . . . . . . . . . . . . . . . . . . . . . 4 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 4 7.1 Normative References . . . . . . . . . . . . . . . . . . . 4 7.2 Informative References . . . . . . . . . . . . . . . . . . 5 Author's Address . . . . . . . . . . . . . . . . . . . . . . . 5 A. Dicussion of alternative approaches . . . . . . . . . . . . . 5 A.1 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 A.2 Implicit PUT extensions . . . . . . . . . . . . . . . . . 5 A.3 Explicit extensions based on RFC2774 . . . . . . . . . . . 6 Intellectual Property and Copyright Statements . . . . . . . . 7 Reschke Expires August 17, 2005 [Page 2]
Internet-Draft The HTTP ADDMEMBER Method February 2005 1. Introduction Frequently, servers may want to allow resource creation through HTTP, but are not able to support HTTP's PUT method for creating new resources, as resource names are completely controlled by the server (see [RFC2616], Section 9.6). This document proposes a new HTTP method called "ADDMEMBER" with semantics similar to those of PUT, except for the fact that the server chooses the URI for the newly created resource. Some alternative approaches are summarized in Appendix A for discussion. 2. Notational Conventions 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]. All terminology not defined explicitly in this document is inherited from [RFC2616]. 3. ADDMEMBER method The ADDMEMBER method requests that the enclosed entity be stored as a new resource under a URI selected by the server based on the Request- URI referring to a container resource. [[anchor4: Do we need to require a specific containment model here, such as WebDAV's collections? --reschke]] If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response, including a "Location" response header containing the URI of the newly created resource. If the resource could not be created, an appropriate error response SHOULD be given that reflects the nature of the problem. The recipient of the entity MUST NOT ignore any Content-* (e.g. Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases. Responses to this method are not cacheable. The fundamental difference between the ADDMEMBER and PUT requests is reflected in the different meaning of the Request-URI. The URI in an ADDMEMBER request identifies the resource that will handle the enclosed entity by storing it as a new resource with a server- selected URI. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some Reschke Expires August 17, 2005 [Page 3]
Internet-Draft The HTTP ADDMEMBER Method February 2005 other resource. ADDMEMBER requests MUST obey the message transmission requirements set out in Section 8.2 of [RFC2616]. Entity-headers in the ADDMEMBER request SHOULD be handled the same way as defined for PUT. This method is neither safe nor idempotent (see [RFC2616], Section 9). 3.1 Example: ADDMEMBER >> Request: ADDMEMBER /CollY HTTP/1.1 Host: www.example.com Content-Type: application/xml <foobar/> >> Response: HTTP/1.1 201 Created Location: http://www.example.com/CollY/3253623 4. Feature Discovery Clients can detect server support for the ADDMEMBER method by inspecting the "Allow" response header returned for an OPTIONS request on the Request-URI. Note that a server may support ADDMEMBER only on a subset of the URIs it is handling. 5. Security Considerations The same security considerations as those for HTTP PUT apply. 6. Acknowledgements [[anchor7: TBD. --reschke]] 7. References 7.1 Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Reschke Expires August 17, 2005 [Page 4]
Internet-Draft The HTTP ADDMEMBER Method February 2005 [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. 7.2 Informative References [RFC2774] Nielsen, H., Leach, P., and S. Lawrence, "An HTTP Extension Framework", RFC 2774, February 2000. URIs [1] <mailto:ietf-http-wg@w3.org> [2] <mailto:ietf-http-wg-request@w3.org?subject=subscribe> Author's Address Julian F. Reschke greenbytes GmbH Salzmannstrasse 152 Muenster, NW 48159 Germany Phone: +49 251 2807760 Fax: +49 251 2807761 Email: julian.reschke@greenbytes.de URI: http://greenbytes.de/tech/webdav/ Appendix A. Dicussion of alternative approaches This section tries to summarize alternative approaches. A.1 POST POST is a very generic method and therefore can be used to achieve the same result. However, clients that rely on the very specific processing defined for ADDMEMBER would need a reliable way to discover how the server is processing POST requests, requiring a new discovery mechanism. A.2 Implicit PUT extensions Several communities are discussing to simply use PUT in these situations. The server would allocate a new URI and send a "Location" response header with the new URI, rather than storing the entity at the Request-URI. This seems to be contrary to the stated HTTP semantics for PUT, but would allow existing clients to make use Reschke Expires August 17, 2005 [Page 5]
Internet-Draft The HTTP ADDMEMBER Method February 2005 of this functionality (although it's not clear how well they would handle the "URI change upon creation" scenario. Example: >> Request: PUT /CollY/something HTTP/1.1 Host: www.example.com If-None-Match: * Content-Type: application/xml <foobar/> >> Response: HTTP/1.1 201 Created Location: http://www.example.com/CollY/3253623 A.3 Explicit extensions based on RFC2774 The extension mechanism defined in [RFC2774] could be used to extend either POST or PUT with the desired semantics. Example: >> Request: M-POST /CollY HTTP/1.1 Host: www.example.com Man: "urn:ietf:id:draft-reschke-http-addmember-00"; ns=00 00-store-enclosed-entity: Content-Type: application/xml <foobar/> >> Response: HTTP/1.1 201 Created Location: http://www.example.com/CollY/3253623 Reschke Expires August 17, 2005 [Page 6]
Internet-Draft The HTTP ADDMEMBER Method February 2005 Intellectual Property Statement 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. Disclaimer of Validity 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 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. Copyright Statement Copyright (C) The Internet Society (2005). 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. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Reschke Expires August 17, 2005 [Page 7]