documentation standards for REST API

jbone at jbone at
Mon Oct 20 14:53:47 PDT 2003


I asked a similar question a while back on [rest-discuss]:

> So we've all been using a variety of ad-hoc mechanisms to describe
> resource models for a while now, including the chatty but pervasive
> sort of "protocol traces" that show the back-and-forth flow of messages
> between a resource provider and consumer / client.  I'm wondering if
> anybody's got preferred formats / standards / conventions for how to
> describe:
> the set of resources that are available
> i.e. the permutations of URIs that are allowed / meaningful
> the set of methods each one takes
> for POST and PUT, the formats and constraints of allowed input
> descriptions of representations / result codes returned by each method
> / input permutation per resource
> Love to see what people are doing in this sense.  I would hazard an
> intuitive guess that a lack of even a semi-formal set of conventions
> for declaratively describing / documenting resource models is one of
> the main sources of friction that we (the REST community) experience in
> trying to communicate with the unenlightened. ;-)

While none of the answers were entirely satisfactory, and I continue to 
use ad hoc mechanisms, (a) I'd love to use something more standard, so 
if you find something let me know ;-) and (b) there were some 
interesting hints at partial, nascent solutions.  I've included the 
substance of a couple of those:

Walden Mathews said:

> I don't know WSDL very well, but I'll conjecture out loud that
> there's nothing stopping you from using it to describe the
> syntax and legal operation/resource space for an application that
> is REST-based.
> Does anyone know why that wouldn't work?  Is this not what you're
> driving at?

to which I replied:

> Yeah, seems that would be kind of like trying to write object-oriented
> assembler.  Or something. ;-)  Possible, tedious, and of high cost for
> dubious benefit.  WSDL appears to me to be extreme overkill and
> low-level cognitive damage for something as simple as a REST-based
> application --- an overcooked layer cake with colorful acronym
> sprinkles.  Doubtless you need it (and the rest of the "stack") if
> you're doing RPCs, but if you're just exposing a resource model --- too
> much.  (Coordination is punted in either case.)
> I think what I'm looking for is something like WSDL that lives at the
> resource / URIspace / HTTP level of abstraction.

Mark Nottingham pointed at his Tarawa work:

> I'm interested in this as well; I've been considering coming up with 
> such
> a format for use with Tarawa[1] so that machine-readable documentation 
> can
> automagically be generated from the annotated code. The list that you
> describe seems about right.
> 1.

...which is great stuff but not really what I was asking about.  But 
check it out anyway.

Tyler Close pointed at the Waterken web calculus stuff, which is 
capabilities-meets-REST in a more rigorous and closed-world framework 
than desired, but interesting from a "spike thinking" perspective:

> The purpose of the Waterken web-calculus is to create a rigorous
> model for building and describing a RESTful interface. The
> web-calculus is a more constrained application of REST than HTTP
> is, but I don't think this is at the cost of any functionality.
> The web-calculus is at:
> A collection of machine generated schemas can be found at:
> A page showing how some of these descriptions were generated is at:
> I would appreciate any feedback on how this model could better
> suit your needs. That said, I am not looking to model all the
> myriad ways in which HTTP allows you to build a RESTful interface.
> I think a more constrained model is needed to enable analysis and
> more automated interoperation.
>> [jb] I would hazard an
>> intuitive guess that a lack of even a semi-formal set of conventions
>> for declaratively describing / documenting resource models is one of
>> the main sources of friction that we (the REST community) experience 
>> in
>> trying to communicate with the unenlightened. ;-)
> I agree. I think a great deal of the friction is based on
> illogical arguments. With a more rigorous model, these arguments
> could be more easily and decisively refuted.

...and Hugh Winkler seemed to think that RDF Schema would suffice:

> It seems like RDF Schema would be a good way to describe any URI
> based web service. For the case of simple GET, you would simply
> supply RDFS describing your schema. For the case of PUT/POST/GET
> with query parameters, you could invent a REST RDF vocabulary
> describing the accepted and returned documents. Below would be a
> description of a reservations service:
> <?xml version="1.0" encoding="UTF-8"?>
> <rdf:RDF xmlns:rdf=""
> xmlns:rdfs=""
> xmlns:rest="">
> 	<rest:Service
> rdf:about="">
> 		<rest:Method>POST</rest:Method>
> 		<rest:Accept rdf:type="#ReservationRequest"/>
> 		<rest:Response rdf:type="#ReservationResponse"/>
> 	</rest:Service>
> 	<rdfs:Class rdf:ID="ReservationRequest"/>
> 	<rdfs:Class rdf:ID="ReservationResponse"/>
> 	<rdfs:Class rdf:ID="CustomerID"/>
> 	<rdfs:Class rdf:ID="FlightID"/>
> 	<rdfs:Class rdf:ID="ReservationID"/>
> 	<rdf:Property rdf:ID="Customer">
> 		<rdfs:domain rdf:resource="#ReservationRequest"/>
> 		<rdfs:range rdf:resource="#CustomerID"/>
> 	</rdf:Property>
> 	<rdf:Property rdf:ID="Flight">
> 		<rdfs:domain rdf:resource="#ReservationRequest"/>
> 		<rdfs:range rdf:resource="#FlightID"/>
> 	</rdf:Property>
> 	<rdf:Property rdf:ID="Reservation">
> 		<rdfs:domain rdf:resource="#ReservationResponse"/>
> 		<rdfs:range rdf:resource="#ReservationID"/>
> 	</rdf:Property>
> </rdf:RDF>
> You would have to design markup describing how to map e.g. the
> ReservationResponse class to some xml schema. (Mapping Definition
> Language is one approach to that problem, could be overkill here).

Anecdotally:  I thought that Baker was working on this at one point in 
time;  not sure anymore.  Also, Dan Connelly and friends have basically 
encircled this space for a long time w/ various formalisms and models 
of Web architecture, but AFAIK nobody yet has come up w/ a single, 
well-liked and general mechanism for either formally or informally 
documenting what you're talking about.

Might want to ping [rest-discuss] to see if the state of the art has 
improved since I asked this question back in May...  I skim the list 
periodically but haven't seen anything.

Good luck!

[NB, tangentially:  drill down one level deeper on this and things get 
even more interesting.  Merely documenting Web-based interaction is 
just a step away from formally / declaratively specifying it.  The 
problem comes in with the impedance mismatch between this interaction 
style and the imperative "application code" we use to implement the 
REST API, and again between that app code and the underlying data 
storage and retrieval model.  Wouldn't it be great if that could all be 
tied together in a simple, terse, declarative specification language so 
you could do soup-to-nuts implementation of Web applications 
declaratively?  There are some signposts along the road already:  
emeijer's work on "Unifying Tables, Objects, and Documents", the 
various Web calculi that have been cropping up lately, folks looking 
hard at Milner's pi-calculus, etc.  (Aside:  pi-calculus gets a bad rap 
because of the "mobile" rhetoric, but then think about it:  doesn't 
"REpresentational State Transfer" already have some implications in 
that regard?)  Anyway, as an industry we're schlepping towards a 
solution already, albeit slowly.]


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: text/enriched
Size: 8182 bytes
Desc: not available
Url :

More information about the FoRK mailing list