| Network Working Group | J. Reschke |
| Internet-Draft | greenbytes |
| Intended status: Informational | February 2005 |
| Expires: August 2005 |
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 in August 2005.¶
Copyright © The Internet Society (2005). All Rights Reserved.¶
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.¶
Distribution of this document is unlimited. Please send comments to the Hypertext Transfer Protocol (HTTP) mailing list at ietf-http-wg@w3.org, which may be joined by sending a message with subject "subscribe" to ietf-http-wg-request@w3.org.¶
Discussions of the HTTP working group are archived at <http://lists.w3.org/Archives/Public/ietf-http-wg/>.¶
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.¶
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. [rfc.comment.1: 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 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.¶
>> 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
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.¶
The same security considerations as those for HTTP PUT apply.¶
[rfc.comment.2: TBD. --reschke] ¶
This section tries to summarize alternative approaches.¶
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.¶
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 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
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
Copyright © 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.¶
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.¶
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.¶