The Well-Formed Web

There is a lot of discussion on the proposed Blogger API Version 2.0 and Ben brings up some very good points. This gives me a chance to trumpet REST in general and RESTLog specifically in how they solve these problems.

Extensibility

The biggest issues brought up were extensibility and compatibility.

But note that, in the case of Movable Type, our interest in this matter is in hoping that tools originally built for the Blogger API can be also used for MT-powered blogs without the loss in functionality that currently exists. [Ben Trott]

And as usual Sam has the answer...

IMHO, the right thing to do is to focus on the bits and bytes that go across the wire. Define an XML message for each interaction. In fact, divide the XML message into two parts - a header which contains "login" information, and a body which contains "post" information. Allow tool specific extensions through namespaces to support "filters", "actions", etc..[Sam Ruby]

Well get back to the "login" information in a minute. The important part is defining an XML message for each interaction. This is exactly what happens in the RESTLog interface. For example when creating a new item or updating it the payload of the message is merely an 'item' fragment from an RSS feed. The payload uses namespaces to support extensions in the same way that RSS does. For example, to create a new item, this is the payload sent to the URL RESTLog.cgi with the verb "POST":

<item xmlns:dc="http://purl.org/dc/elements/1.1/">
      <title>My Summer Vacation</title>
      <description>On my summer vacation I went to...</description>

      <link>http://127.0.0.1/cgi-bin/RESTLog.py/4</link>
      <dc:date>2002-10-28T22:18:53-05:00</dc:date>
</item> 

Note that the date comes from the Dublin Core namespace. Using namepaces in this way is how the interface gets extended. For example, to extend this interface to accomodate the power of Movabletype you could use Phil Ringnalda's RSS Extension Module for Movabletype. To create an item that was only a draft and that added an excerpt and some keywords:

<item xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:mtblog="http://purl.org/net/rssmodules/mtblog/">
      <title>My Summer Vacation</title>
      <description>On my summer vacation I went to...</description>

      <link>http://127.0.0.1/cgi-bin/RESTLog.py/4</link>
      <dc:date>2002-10-28T22:18:53-05:00</dc:date>
      <mtblog:status>Draft</mtblog:status>
      <mtblog:excerpt>What I did over the summer.</mtblog:excerpt>
      <mtblog:keywords>vacation beach disney</mtblog:keywords>
</item> 

Two important things to note about this extension. The first is that is re-uses work that was already done. Anybody that knows RSS should be able to read and manipulate this interface. The second thing to note is that it is backward compatible. Old clients that do not understand the new items in the 'mtblog' namespace will just ignore them.

Authentication

Now we'll get back to authentication which Sam mentioned and which Ben also brings up:

What I would have been interested to see, aside from the above-mentioned complaints, is a revamped authentication system.[Ben Trott]

This is where RESTLog really shines by basically punting on the problem. The idea here is again to reuse what has already been done, and in this case use the authentication mechanisms that already exist. HTPP already has two authentication mechanisms built into it, Basic and Digest. These are already done and RESTLog gets them for free. Note that if new authentication mechanisms are added to HTTP, or for example you are in a closed environment and want to use Microsoft's Domain authentication, then RESTLog again gets those for free. As long as the server software supports the authentication mechanism then RESTLog can use it. In the case of RESTLog the server needs to be configured to restrict access to clients doing a POST on the URL RESTLog.cgi, and if you look at the rest of the RESTLog interface you would see that in general you want to restrict POST, PUT and DELETE verbs. Using security in a REST interface comes down to setting security for verbs on URLs, there is no need to peek inside the contents of the message to determine if authentication is needed. Using Apache this is easy to implement. Here is an example .htaccess file that would be appropriate for RESTLog:

AuthType Basic
AuthName DAV
AuthUserFile /some/path/user.password
<LimitExcept GET>
Require valid-user
</LimitExcept>

I hope this provides some food for thought and shows some of the advantages of a RESTian API.

Footnote: I know that both Ben and Mena work on Moveabletype. In all my comments above I have addressed them to Ben because that is the attribution given on the weblog entry. I have no way of knowing if that post was a joint effort by both Ben and Mena and mean no disrespect to Mena by not addressing my response to her.