More on Atom

Posted Friday, February 20, 2004 10:16 am

So Sam Ruby and I have been conversing via email and I have predictably been unable to convince him that anything about the Atom spec is wrong. From our emails, it seems that the Atom API is perfect - at least on all the points that I take exception with. He has said that the Blogger and TypePad guys have both implemented the SOAP version of the API and Sam is in favor of making section 7.1 of the spec dealing with the SOAP alternative, a MUST instead of a SHOULD. That's a good first step, but it doesn't make any steps to improving the general simplicity or consistency of the API. Yeah, you can use POST instead of PUT/DELETE - if you're willing to put up with the added complexity and processing that SOAP entails, and are willing to trust that REST guys made a decent effort to support that version (which is a long stretch).

Here's the problems as I see it now: these two methods are not true peers. First, I don't like SOAP. No one does. Look at Amazon's API for an example - there's like a 10 to 1 use of the basic XML-via-HTTP over the SOAP API. Secondly, the results from the SOAP calls are not *exactly* the same as their equivalent REST call.

Here's my suggestion of how to implement the non-REST calls to Sam:

POST /t/atom/weblog/blog_id=1 HTTP/1.1
Host: www.typepad.com

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:api="http://purl.org/atom/api#">
   <api:username>USERNAME<api:/username>

   <api:password>PASSWORD</api:password>
   <api:nonce>NONCE</api:nonce>
   <api:created>2003-09-08T05:52:36Z</api:created>
   <api:action>POST</api:action>

   <title>Trip to the Lake</title>
   <dc:subject>Vacation</dc:subject>
   <content type="application/xhtml+xml" mode="xml"><div xmlns="http://www.w3.org/1999/xhtml"><img src="http://example.typepad.com/photos/vacation/lake-thumb.jpg" /> Here is a picture of me at the lake.</div></content>

</entry>

POST /t/atom/weblog/blog_id=1 HTTP/1.1
Host: www.typepad.com

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#" xmlns:api="http://purl.org/atom/api#">
   <api:username>USERNAME<api:/username>
   <api:password>PASSWORD</api:password>

   <api:nonce>NONCE</api:nonce>
   <api:created>2003-09-08T05:52:36Z</api:created>
   <api:action>DELETE</api:action>
   <id>tag:typepad-com:post:3</id>

</entry>

POST /t/atom/weblog/blog_id=1 HTTP/1.1
Host: www.typepad.com

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#" xmlns:api="http://purl.org/atom/api#">
   <api:username>USERNAME<api:/username>
   <api:password>PASSWORD</api:password>

   <api:nonce>NONCE</api:nonce>
   <api:created>2003-09-08T05:52:36Z</api:created>
   <api:action>UPDATE</api:action>
   <id>tag:typepad-com:post:3</id>

   <title>Trip to the River</title>
</entry>

The main difference between these examples that the SOAP examples on the DifferentlyAbledClients page is that 1) It doesn't rely on the SOAP stuff, and 2) the results are *exactly* the same as the REST requests. Actually, I'd like to clean this up even more and include more control tags in the entry stanza, including the blog id. Basically there should be *ONE* endpoint for the ATOM stuff - a servlet or cgi-bin script - and the XML describes both the data and what happens to it.

Additionally, there can be added functionality in the action tag, such as SENDALERT which could notify the end user of a message via SMS - or SENDMMS which could send that entry to a user via MMS, or lots of other non-REST examples. REST verbs should not limit what you can do with the spec. Right now, using SOAP, clients have these odd requirements: "Clients SHOULD use the appropriate HTTP Method when possible. When not possible, they should use POST and include a SOAPAction HTTP header which is constrained as follows: SOAPAction: 'http://schemas.xmlsoap.org/wsdl/http/[METHOD]' Where [METHOD] is replaced by the desired HTTP Method." Okay, so on a limited client, I'm writing some code that deals with REST calls and some code that deals with SOAP, and praying that the server understand both and returns the same results as other peers. Sure, that's makes sense.

Atom needs the simplest solution that could possibly work and not all this headache.

-Russ

< Previous Next >