Abstract
This proposal extends the Atom protocol to allow servers to optionally support creation of entries or resources by using the HTTP "PUT" method directly to a URI location beneath a base URI.
Status
Open -- incomplete
This proposal has been separated from PaceNonEntryResources and is expanded to support PUT-to-create for <entry> resources.
Rationale
The use cases for this support are:
-
wikis, blosxom and blosxom-derived, and similar publishing systems, which allow new entries to be created at URI locations beneath a base URI.
-
creation of named non-entry resources such as images, media, documents, templates, stylesheets, downloads, etc.
An alternate suggestion was to use a "name hint" with a PostURI/ResourcePostURI. This proposal provides a more concrete indication to clients whether the server supports server generated URIs (PostURI/ResourcePostURI) or/and user/client generated URIs (BaseURI/ResourceBaseURI).
This proposal is believed to be upward compatible with WebDAV. Note in the proposal that PUTing to a "deep" hierarchy may require external means for creating the deeper path segments, such as an administrative web page within the publishing system or via WebDAV's MKCOL method.
Proposal
In the protocol document, add to 4.2 Terminology:
-
BaseURI
-
A URI that when combined with a user-specified component is used to create an entry resource with locations assigned by the client, using the HTTP verb PUT.
-
A URI that when combined with a user-specified component is used to create non-entry resources with locations assigned by the client, using the HTTP verb PUT.
In 4.3 The AtomAPI Model, delete "There are three major classes of URIs in this specification: PostURI, FeedURI and EditURI." and add the following to the summary list of URIs:
-
BaseURI: PUT
-
ResourceBaseURI: PUT
In section 5.4.1 Link Tag @rel, add:
-
service.base
-
The base URI in the href attribute is used in combination with a user or client specified final component to create new entry resources.
-
The base URI in the href attribute is used in combination with a user or client specified final component to create new non-entry resources.
As originally noted in PaceNonEntryResources, it is recommended that the access patterns (how to use POST, PUT, GET, DELETE in a generic fashion) should be separated from the descriptions of the specific URIs. That refactoring will go in a different Pace. Depending on the status of that Pace, this Pace is incomplete until spec text is added either in the current style or the style of the other pace.
The section describing ResourcePostURI and ResourceBaseURI will note:
-
Multiple ResourcePostURIs and/or ResourceBaseURIs with differing @title attributes may be provided for allowing different kinds of resources to be located separately, such as stylesheets, icons, documents, multimedia, or other resources.
In section 6, Security Considerations, it should be noted that client-specified URIs used with PUT when creating new resources should be checked.
Impacts
ResourceBaseURI conflicts with API section 7.1 SOAP Enabling. The second alternate proposal in PacePutDelete's, Atom-Action header, would work.
Notes
See also: Pace409Response