mark nottingham

A Description Format for REST

Sunday, 7 December 2003

HTTP APIs

Adam asks if there’s a description format for REST. I don’t know of any that have wide acceptance (and I think the hard-core RESTafarians will answer “REST is self-describing, that’s the point” ;) but I have been noodling on something for my own purposes.

So far, I have a sample XML file that describes the RESTLog API (with some modifications to make it more interesting), as well as a stylesheet to do code generation for Tarawa (which is also still in progress).

Comments / suggestions welcome. I’m particularly interested to see if it’s adequate to describe other kinds of REST-based APIs (including everyday Web sites), whatever they may be. It explicitly isn’t designed to describe every possible URI-based API, but rather a reasonable and well-behaving subset. In other words, it’s intended to encourage good URI design, rather than the current state of the Web.

I’m also working on a spec, as well as a stylesheet to HTML.

P.S. - this has actually been sitting on my machine for a few months; it was always “not quite done yet, need to spiffy it up a bit more.” I need to get it through my head that it’s just better to throw it over the fence sometimes, and see what happens.


3 Comments

Leigh Dodds said:

Is there an overlap here with Mark Baker’s RDF Forms?

http://www.markbaker.ca/2003/05/RDF-Forms/

Monday, December 8 2003 at 2:15 AM

Hans Gerwitz said:

I’ve been looking for something just like this for a project. Thanks for inventing this wheel for me ;-)

BTW, although I ended up here on a completely different mission, much of your writing on caching has been very valuable in the past. So, thanks for that, too.

Tuesday, December 9 2003 at 8:12 AM