documentation standards for REST API

Lucas Gonze lgonze at
Mon Oct 20 15:53:45 PDT 2003

That's cool stuff, Jeff.  The RDF bits in particular are informative.  
An alternative you didn't mention is BNF.

Check out also the section "Detailed Outline" in

- Lucas

On Monday, Oct 20, 2003, at 17:53 America/New_York, jbone at 

> Lucas,
> 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.]
> jb
> _______________________________________________
> FoRK mailing list

More information about the FoRK mailing list