The HTTP ADDMEMBER Methodgreenbytes GmbHHafenweg 16MuensterNW48155Germany+49 251 2807760+49 251 2807761julian.reschke@greenbytes.dehttp://greenbytes.de/tech/webdav/
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
.
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 , 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
for discussion.
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 .
All terminology not defined explicitly in this document is inherited
from .
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. Do we need to require a specific containment
model here, such as WebDAV's collections?
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 .
Entity-headers in the ADDMEMBER request SHOULD be handled the same way
as defined for PUT.
This method is neither safe nor idempotent (see , Section 9).
>> 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.
TBD.Key words for use in RFCs to Indicate Requirement LevelsHarvard Universitysob@harvard.edu
General
keywordHypertext Transfer Protocol -- HTTP/1.1University of California, Irvinefielding@ics.uci.eduW3Cjg@w3.orgCompaq Computer Corporationmogul@wrl.dec.comMIT Laboratory for Computer Sciencefrystyk@w3.orgXerox Corporationmasinter@parc.xerox.comMicrosoft Corporationpaulle@microsoft.comW3Ctimbl@w3.orgAn HTTP Extension FrameworkMicrosoft Corporation1 Microsoft WayRedmondWA98052USAfrystyk@microsoft.comMicrosoft Corporation1 Microsoft WayRedmondWA98052USApaulle@microsoft.comAgranat Systems, Inc.5 Clocktower Place, Suite 400MaynardMA01754USAlawrence@agranat.com
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 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