Abstract
The Rev 9 of the draft AtomAPI defines an optional SOAP Enabling. This proposal substitues a simpler mapping for clients that do not support PUT and DELETE
Status
Withdrawn
Rationale
-
Some clients can not do PUT/DELETE
-
SOAP tunnels *everything* under POST, this proposal keeps GET and enourages good RESTful design. [ The previous proposal kept GET when possible as well ]
-
Simpler than bringing in full SOAP
Proposal
Replace section 7.1 with the following:
7.1 Restricted Client Enabling
Servers MUST support the following alternate interface mechanisms to enable a wider variety of clients to interact with AtomAPI servers. The following requirements are in addition to the ones listed in the Functional Specification Section.
7.1.1 Servers
-
All servers MUST support the limited use of the atom:action element as described below in the Client section.
7.1.2 Clients
-
Clients MUST support GET and POST in all the places specified in the Functional Specification Section.
-
Clients SHOULD use the HTTP methods PUT and DELETE HTTP Method when possible. When not possible, they MAY use POST and include an atom:action element which may contain the value of "PUT" or "DELETE" to reflect the desired action. The 'action' element is a child of the 'entry' element and it's only allowable values are "PUT" and "DELETE".
Examples
Canonical
Here is how DELETING an entry is done now.
DELETE /path/myLastEntry.atomapi HTTP/1.0 Host: example.com X-WSSE: UsernameToken Username="USERNAME", PasswordDigest="PASSWORDDIGEST", Nonce="NONCE", Created="2003-09-08T05:52:36Z"
Alternate
This is how it can be done from a client that does not support PUT/DELETE.
POST /path/myLastEntry.atomapi HTTP/1.0 Content-type: application/atom+xml; charset=utf-8 X-WSSE: UsernameToken Username="USERNAME", PasswordDigest="PASSWORDDIGEST", Nonce="NONCE", Created="2003-09-08T05:52:36Z" <?xml version="1.0" encoding='utf-8'?> <entry xmlns="http://purl.org/atom/ns#"> <action>DELETE</action> </entry>
Canonical
Here is how to PUT an entry now.
PUT http://example.com/myRecentEntry HTTP/1.0 Host: example.com X-WSSE: UsernameToken Username="USERNAME", PasswordDigest="PASSWORDDIGEST", Nonce="NONCE", Created="2003-09-08T05:52:36Z" <?xml version="1.0" encoding='utf-8'?> <entry xmlns="http://purl.org/atom/ns#"> <title>Some Entry</title> <id>http://example.com/myRecentEntry</id> <issued>2003-09-08T03:32:51Z</issued> <content type="text/plain">This is just an example.</content> </entry>
Alternate
This is how it can be done from a client that does not support PUT/DELETE.
POST http://example.com/myRecentEntry HTTP/1.0 Content-type: application/atom+xml; charset=utf-8 X-WSSE: UsernameToken Username="USERNAME", PasswordDigest="PASSWORDDIGEST", Nonce="NONCE", Created="2003-09-08T05:52:36Z" <?xml version="1.0" encoding='utf-8'?> <entry xmlns="http://purl.org/atom/ns#"> <action>PUT</action> <title>Some Entry</title> <id>http://example.com/myRecentEntry</id> <issued>2003-09-08T03:32:51Z</issued> <content type="text/plain">This is just an example.</content> </entry>
Impacts
* Current REST based implementations of the client and server will need to add processing for the atom:action element.
* REST implementations will have to reconcile the action tag (if present) with the http method.
* Implementations serializing an entry will have to remove the action tag.
* this proposal requires an "atom:action" element to be added to the format spec.
* without response examples, this proposal implies that the HTTP response codes can be used. That would seem to run counter to RFC3205
Notes
Alternate Proposal
Replace section 7.1 with the following:
7.1 Restricted Client Enabling
Servers MUST support the following alternate interface mechanisms to enable a wider variety of clients to interact with AtomAPI servers. The following requirements are in addition to the ones listed in the Functional Specification Section.
-
All servers MUST support the limited use of the Atom-Action: header as described below in the Client section.
7.1.2 Clients
-
Clients MUST support GET and POST in all the places specified in the Functional Specification Section.
-
Clients SHOULD use the HTTP methods PUT and DELETE HTTP Method when possible. When not possible, they MAY use POST and include an Atom-Action header which may contain the value of "PUT" or "DELETE" to reflect the desired action.
-
The Atom-Action header has as it's only allowable values "PUT" and "DELETE". The value of the Atom-Action header is case-sensitive.
-
The Atom-Action header can only be used in conjuction with a POST.
Alternate DELETE
POST /path/myLastEntry.atomapi HTTP/1.0 Content-type: application/atom+xml; charset=utf-8 X-WSSE: UsernameToken Username="USERNAME", PasswordDigest="PASSWORDDIGEST", Nonce="NONCE", Created="2003-09-08T05:52:36Z" X-Atom-Method: DELETE
Alternate PUT
POST http://example.com/myRecentEntry HTTP/1.0 Content-type: application/atom+xml; charset=utf-8 X-WSSE: UsernameToken Username="USERNAME", PasswordDigest="PASSWORDDIGEST", Nonce="NONCE", Created="2003-09-08T05:52:36Z" X-Atom-Method: PUT <?xml version="1.0" encoding='utf-8'?> <entry xmlns="http://purl.org/atom/ns#"> <!-- This entry, however, is very necessary and also the exact same entry that would be PUT in the "canonical" form. --> <title>Some Entry</title> <id>http://example.com/myRecentEntry</id> <issued>2003-09-08T03:32:51Z</issued> <content type="text/plain">This is just an example.</content> </entry>
This only works if the restricted clients can add extension headers (something which Atom's X-WSSE authentiaction mechanisim also requires).
MarkBaker prefers the alternate proposal, as there's a better separation of concerns between the protocol and data format. Also, HTTP headers shouldn't use "X-", and I don't think this header has to be Atom specific, hence I'd prefer something like "ActualMethod".