3

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?

  • 1
    I think you should find a similar question on SO, it may have answers already. – Vince May 21 '13 at 22:12
  • Thanks, SO does have quite a few entries on WADL, though none address my question explicitly with opendata API examples using WADL. I believe SO is really aimed at answering questions that involve writing some code, whereas my question just involves examples of opendata APIs (or reasons why they don't exist?); similar to many questions here. – cboettig May 22 '13 at 15:04
3

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):

  • Thanks for both the examples and the explanation; I'm coming around to the "document the mediatypes" not the client calls idea. – cboettig May 23 '13 at 19:35
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?

  • This depends how complex the API is and the tasks we use it for. For instance, if we can also upload to the API, or need to handle authentication/OAuth, having objects makes sense (e.g who interacts with Twitter API with raw api.get commands instead of the python/R/ruby/etc library for its API?) – cboettig May 22 '13 at 4:35
  • If the API changes, an automated generation of objects can be updated immediately, while those hand-crafted implementations cannot. Though this is a traditional advantage of SOAP, many new & successful APIs are RESTful, and WADL appears to promise a similar capacity for automatic object generation, but I haven't seen good examples. Hence my questions above... – cboettig May 22 '13 at 4:38
  • Actually, OAuth was the precise thing I was thinking of with api.get('/...'). I'm not sure about the "changing API, changing object" thing - wouldn't you still need to adapt your code if any of the attributes or behaviour changed? – pudo May 22 '13 at 6:07
  • Only if the changes broke existing API calls. If the API simply added new options or functions, the library would automatically be updated to include them... – cboettig May 22 '13 at 15:05
2

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.