RESTLog Interface Specification

The RESTLog interface is defined in Table 1. The table lists the URLs, the verbs that can act on those locations, the mime-type of the content and a description of the results of that action.

N.B. The URL RESTLog.cgi is used as a placeholder for the implementations real URL. For example, the real URL could easily be http://bitworking/RESTLog.py or http://WellFormedWeb/news. The RESTLog interface does not define what the URL is, instead it defines the actions that are allowed on that URL and the format of the responses. For example, I can hand you a URL such as http://bitworking.org/stories and tell you that it conforms to the RESTLog interface and you can perform, modulo security restrictions, all of the actions listed below on that URL.

Interface

Table 1
*The RESTLog Interface*
URL	Verb	Type	Description	Format
RESTLog.cgi	GET	html	Retrieves the main web page.
	GET	rss	Retrieves the RSS file.
	POST	xml	Creates a new news item.	RSS Fragment
RESTLog.cgi/itemID	GET	html	Retrieves the item transformed into an HTML page.
	GET	xml	Retrieves the xml form of the item, i.e. as an RSS 2.0 'item' fragment.	RSS Fragment
	PUT	xml	Putting an item replaces it's contents. This is how editing an item is done.	RSS Fragment
	DELETE	-	Delete the item.

Verb: The HTTP verbs that can operate on the given URL. HTTP defines a standard set of verbs and we are only using a subset of them here.
Type: Type is just a shorthand for the mime-type of that transaction. Normally selecting the mime type is handled through content negotiation for GETs and specified in the Content-Type for PUTs and POSTs. Content-type can also be forced on a GET by appending a ?Type to any URL. For example, a link to the RSS file would be /RESTLog.cgi?rss.

Table 2
*Type mappings*
Type	MIME-type
xml	text/xml
html	text/html
rss	application/rss+xml

Format

All the actions that deal with content type 'xml' are transporting items. Items are formatted as 'item' elements from RSS 2.0. The items must additionally conform to the RSS 2.0/XSS-extensible profile with the exception of defining the default namespace. For example:

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

This example shows only a minimal number of elements. An implementation must no reject modules it doesn't know about, though it is free to ignore them.

Further note that the contents of the 'item' element are guided by the RSS 2.0 specification, which states that all elements are optional, but requires that at least one of 'title' or 'description' are present.

Usage

To create a new item on the weblog the publishing client would format the new item as an 'item' element of RSS 2.0 and POST that to the URL RESTLog.cgi. GET, PUT and DELETE on the URL RESTLog.cgi/itemID are used to manipulate an individual item. The client software can do a GET to retrieve the most recent version of the XML for the item to be displayed for editing by the user. After the user had edited the item it can be PUT back and the items content will be replaced with the PUT copy. Removing an item completely can be done by doing a DELETE on the URL.

Currently most (none?) of the news aggregators don't do content negotiation, so you will need to feed them the URL /RESTLog.cgi?rss which they can use to get the RSS feed.

Notes

13-March-2003: Added some anchors and started removing content negotiation. After using content negotiation in the field for a while it just seems to cause more trouble than it's worth. Many agents do not send 'accept' headers along. This causes problems with validators, transformation agents (like XSLT Services) and possibly buggy browsers. A good rule of thumb I learned from this exercise is "One mime-type per URL".

2003-01-06

BitWorking