Should I use WADL to describe my RESTful API?

Question

I'm about to embark on a project that makes extensive use of a properly RESTful approach. That is, it uses HATEOAS and serves up resources in a manner that allows for general exploration by a client.

I would like to ensure that I provide a description of my endpoints in a manner that would allow client applications to be automatically generated in a wide variety of languages. I understand that for SOAP based web services I can use WSDL and that apparently there is WSDL2 that provides greater definition of the HTTP verbs in use with REST. However I see many articles swinging back and forth over it's utility.

So, should I use WADL to allow external code generators to quickly build a client for my web application or is there a better standard that is expected?

Answer 1

My advice is not to bother. WADL has not been that widely adopted See this question on Stack Overflow and there are some strong views that's it's not a good fit with the kind of 'proper' REST you describe, as shown here on another Stack Overflow question.

WADL descriptions are time consuming to build (and mostly manual) and they add a brittleness that HATEOAS is designed to avoid - i.e. you'll have some well defined entry points but exactly how your client proceeds is then determined by opaque links, not a predefined 'contract'.

That's not to say you should run away entirely from documentation, schema definition, etc, though theres an end of the RESTifarian spectrum that would suggest you can approach such a high level of self-description you don't need them. I've not found this to be the case in practice. A few solid worked examples should be all an unfamiliar developer needs. And knock up a few clients for your own API to try it out (easy enough from JQuery). That will give you a good indication whether you're building something consumable or not.

A good source of information in this area is the Hypertext Application Language. I find some of it a little heavyweight, but the debates on the mailing list are good and current and relevant.

Hope that helps you get started.

Answer 2

The state of REST interfaces as driven from anything other than an interactive browser isn't very good. HATEOAS is a nice principle, but it leads to interfaces that are very strongly people-oriented and it tends to lead to the burden of the user interface being put on the service developer (who is usually pretty busy making the service itself work).

WADL itself isn't too great; it doesn't really capture enough of the semantics of the service to make it possible to tool things up. Of course, this is a hard problem in general. WSDL rarely exposes enough information either, and that's had a lot more effort put into the problem (it's possible to attach enough information, but hardly anybody actually does so).

Yet it is telling that a colleague of mine has spent months working on a library that uses a REST interface to a service, and the WSDL-described interface to the same service^[*] was tooled automatically to nearly the same quality in seconds; going the rest of the way was about a day of writing wrapping classes. My hunch (based on a limited sample size) is that you cannot get rid of all brittleness in a complex service because the semantics of the service will inevitably evolve over time, and that REST is better at driving interfaces for humans while SOAP is better for interface libraries (there's good WSDL/SOAP client tooling for almost all languages of note). Unless you've got the luxury of doing both, which one to focus on should depend on which set of clients you care about most.

I wouldn't put much effort into WADL, but if your REST framework will produce it for you (Apache CXF does this) then there's no particular reason to not provide it. Anyone who wants to tool off your code will want WSDL+SOAP.

---

^{[*] As the author of the service in question, I can say for sure that both interfaces supported the same operations — there was a common underlying abstract model — and in a “natural” style for both interface types. On the service side, it was definitely the case that some things were easier with REST and others with SOAP.}

Answer 3

The W3C has made a formal recommendation for a REST documentation standard based on WSDL 2.0. Here is a quote from the IBM article:

The term Web services is typically associated with operation- or action-based services using SOAP and the WS* standards, such as WS-Addressing and WS-Security. The term REST Web services generally refers to a resource-based Web services architecture that uses HTTP and XML. Each of these architectural Web service styles has its place, but until recently, the WSDL standard didn't equally support both styles. The WSDL 1.1 HTTP binding was inadequate to describe communications with HTTP and XML, so there was no way to formally describe REST Web services with WSDL. The publication of WSDL 2.0, which was designed with REST Web services in mind, as a World Wide Web Consortium (W3C) recommendation means there is now a language to describe REST Web services.