Tuesday, January 26, 2010

WADL toolbox

WADL stands for Web Application Description Language and currently is in a state of W3C Member Submission, that means at the early stage of W3C standardization process. The purpose of the "language" is similar to WSDL, with the orientation towards RESTful APIs in the first place. What is essential for me is that this language perfectly suits the task of Pomodoro Server API description. There are surprisingly few tools utilizing this format, I guess this is due to the immaturity of the language. Though I can name some of the most useful ones:
  • Jersey, a reference implementation of JAX-RS. It is able to generate WADL at run time based on the metadata found in your Java classes.
  • soapUI, a great tool for testing web services. As one of its numerous new features in version 2.5 it can utilize WADL web service description and generate sample test cases automagically. It can even do the trick in the opposite direction, i. e. infer both WADL and XSD from the existing test case structure! Unfortunately I've found some aspects of this generation somewhat buggy not really obvious. For example, it does not inherit template parameters for nested resources. And despite the ability to specify application-wide settings for HTTP Basic Auth, it does not get applied somehow, so it should be specified for each test case separately. Anyway, it is a great tool and I'm looking forward to see it in a bit more stable state.
  • WADL to HTML is an advanced XSLT stylesheet to generate documentation from your WADLs. It seems that either my WADL is all wrong (then why it conforms to the WADL Schema?), or my XSLT processors are broken (both Saxon and Xalan running on Windows and Linux), because I was unable to get any output. But they say it works for them, so I tend to think it is actually my own problem. Anyway, I've already wrote my own simple XSLTs and going to put it here in a matter of few days :)
  • wadl2java generates a web service client based on WADL. It uses JAXB to create the necessary representations based on XSD referred in grammars section.
  • REST Describe & Compile is yet another client generator. It can infer WADL from the set of supplied request URLs, and then generate client code in several languages, namely Java and Python. The tool looks promising, but as for me, the UI is not intuitive enough. Also, you have no control over code generation, so good chances are that you will have to modify your clients manually after generation. Here you can find a great deal of documentation for the tool and underlying concepts.
P. S.: You can find WADL for Pomodoro Server here. Also you can see some generated documentation in the Google Code wiki.


  1. Your post would tend to indicate that you have not discovered any decent tools that can infer WADL from a set of sample URL requests. I've spent a couple of days searching around with no luck.

    Soap UI Pro is not automated enough (especially for the price). And Rest Describe & Compile is not polished enough.

    I'm mulling over whether I should write something to handle batches of URLs the way Rest Describe & Compile does only with a more intuitive approach.

    Does anyone have any thoughts around this topic?

  2. Well, actually you are right, WADL infer I've seen so far is not perfect. But the WADL syntax is so simple that I see no problem in writing it manually in any XML editor supporting validation against XML Schema. At least you will know for sure that you'll get exactly what you want.

    Also, WADL describes your system's API and communication protocol, and it is a very important part of your application. From my point of view, it is better to carefully handcraft your WADL, and then generate some code, docs (including sample URLs) and tests out of it.

  3. Regarding the WADL to HTML XSLT's of Mark Nottingham ... I too was unable to get them to work. But finally it dawned on that the URL for the WADL specification has changed. Once I changed 'http://research.sun.com/wadl/2006/10' to 'http://wadl.dev.java.net/2009/02' (in two places) I was able to get them to work. Hooray!

  4. Do you have a WSDL to WADL converter or know of one?

    1. I am also trying to find a tool to generate a WADL from WSDL. My project has 32 SOAP services and my customer is asking me to have a JSON representation for al the services. So i am planning to create a WADL from WSDL using XSLT.

  5. I am trying to use WADL in .Net can i consume the service or else is there any converter to convert WADL to WSDL?