Self-documenting RESTful APIs: examples with WADL?

Question

One of the hurdles in taking advantage of a data API, particularly the ever more popular RESTful APIs, is either in implementing or finding an existing implementation of the API in one's programming language of choice. (Of course this step isn't strictly necessary, but there are almost always advantages of having a complete implementation rather than hacking away with whatever one's favorite curl library might be).

Thanks to their high structure, one can often automatically generate such an implementation for SOAP-based APIs (e.g. R users might see the SSOAP package which does this).

I don't believe such a thing is inherently possible with RESTful APIs, but I understand one might be able to programmatically generate these functions if the RESTful API provided WADL documentation. (e.g. it seems there the omegahat project has a preliminary R package to do so). I am looking for examples of open data APIs that provide such WADL documentation. How common is this format? Is there a reason it is not more widely adopted? Are there convenient ways for API providers to generate WADL documentation without simply hand-coding the XML?

Answer 1

Code generation is often considered to be an anti-pattern for REST APIs: the goal is to allow clients and servers to evolve independently as much as possible. Generating client code from a WADL document, as you might do from SOAP, will make the client brittle to server-side changes. It'd be better to "bootstrap" the client by consuming the WADL at run-time rather than compile time.

Having said that, here's a couple of quick examples of WADL used on some public APIs (I've not checked the data licensing, so aren't necessarily "Open Data" APis):

• Launchpad: https://help.launchpad.net/API/Hacking
• D&B direct: http://dnbdirectapps.com/docs/1.0/rest

Answer 2

I haven't looked at WADL in detail, but I think that if you want a fully described service, SOAP may be the right thing in the first place?

The success of RESTful services can, I believe, in large part be attributed to their lack of formalism. An interface that emits and consumes JSON can be made somewhat self-explanatory through the use of URIs for entity identification and operations like pagination. Everything else can be explained in human language (I particularly like Twitter's object guide in that regard).

In the same sense, generating a full set of objects seems unusual - given a simple resource, abstracting beyond basic HTTP methods often doesn't really make much sense: do you really need an object, or is api.get('/foo/5.json') good enough?

Answer 3

Just another view on this. I've been working in and around REST and RESTful APIs for a while, sometime going deep down the Hypermedia api sometimes not.

With a hypermedia based API the intention is not to have many documented endpoints into the API but a small number of or even single endpoint from which the client can walk the API to find what they are looking for.

For example, one of our APIs provides a single end point which when requested tells the user there are two further endpoint, one to request an access token given your account details and another to create an account. If the user does either of those things the API informs them of the new options available, resources present etc. Each resource maintains links to it's available operations and children. See something like this HAL browser demo

The idea here is that the API can in some sense self document, it may not always be the right thing to do but another option none the less.