Open Stack

On 26/10/2011, at 9:34 AM, Caitlin Bestler wrote:

> WADL sounds like a wonderful validation tool.
>  
> But shouldn’t our primary goal be finding a consistent way to describe the APIs
> for *application developers*.
>  
> Syntax tools, whether ancient notations like BNF or the latest XML concoction only tell you the syntax of the operation.
> There also has to be consistent information that provides information to the reader as to when and why they would use
> this specific operation, not just how to format it.
>  
> There is also a tendency of syntax oriented tools to omit vital state information,  particularly the expected sequence of operations

Certainly, we need better documentation of the APIs; that's an ongoing process. The tools that we use can help -- or hinder -- the creation of better docs. 

I'm not married to WADL -- despite having a hand in its creation, I've never been entirely comfortable with it. However, there isn't (yet) anything better available, AFAICT (although swagger does look interesting). 

WRT sequencing -- agreed. One of the interesting things that has come up repeatedly in the discussion of hypertext-based APIs was that if you do it correctly, you only present the client with the links that are valid for their state, thereby naturally enforcing the state machine. Of course, you still need to be able to document things so that consumers can get an overview. 

Cheers,

--
Mark Nottingham   http://www.mnot.net/