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?

  • 1
    Wow - 2 days and just the quiet rustling of the wind through the tumbleweeds...
    – Gary
    Feb 6, 2012 at 10:30
  • Absolutely not. WADLs are possibly the worst API documenters I've come across to date. Feb 23, 2016 at 23:47

3 Answers 3


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.

  • 2
    +1 for a good answer. This confirms the suspicions that I've been having about it and re-inforces my current approach (consume your own API to see how rubbish it really is).
    – Gary
    Feb 7, 2012 at 10:37

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.

  • +1. My company and it's relatives are in that period of "Who needs SOAP, we have REST!". We create simple REST wrappers around our SOAP services. Not everything can be simple or obvious. Sometimes it's hard and complicated. So we present 3rd parties with a REST interface defining the handful of fields they're interested in. This wraps a SOAP service with it's super complicated-but-flexible input and output documents. We use WCF "dual interface" services, where both SOAP and REST endpoints are generated from the code (generated from Xsd Schema written with XmlSpy).
    – RoboJ1M
    Oct 16, 2014 at 9:55

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.

  • That article was written in 2008, while WADL itself was only submitted in 2009. So it's far from fair recommendation. Now I'm curious what is the state in 2017, 10 years after the W3C WSDL 2.0 recommendation ... The latest version of WSDL today is still the same 2007 WSDL 2.0. Not a single progress (compared to, say, HTML and HTTP). I wonder if that's a good thing? Sep 14, 2017 at 11:00

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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