UserPreferences

PacePutDelete


Abstract

The [WWW]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

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
  1. All servers MUST support the limited use of the atom:action element as described below in the Client section.

7.1.2 Clients
  1. Clients MUST support GET and POST in all the places specified in the Functional Specification Section.

  2. 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 [WWW]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.

  1. All servers MUST support the limited use of the Atom-Action: header as described below in the Client section.

7.1.2 Clients
  1. Clients MUST support GET and POST in all the places specified in the Functional Specification Section.

  2. 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.

  3. The Atom-Action header has as it's only allowable values "PUT" and "DELETE". The value of the Atom-Action header is case-sensitive.

  4. 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".


CategoryProposals