Joe Gregorio
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
| URL | Verb | Type | Description | Format |
|---|---|---|---|---|
| RESTLog.cgi | GET | html | Retrieves the main web page. | |
| 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. | |
| 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.
| 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".