The WADL Dilemma

The Web Application Description Language (WADL) is now being acknowledged by many as a language which is practical, functional, very capable of describing the advanced RESTful web services and yet simple and easy to read and understand.

WADL has now been submitted to W3C which is a great achievement for Marc Hadley. What is really unique about this submission is that it has not been submitted by the usual suspects like Microsoft and IBM but rather by the individual author. It seems that the time when various web services specifications have been discussed by a number of years by various companies is behind us, but you never know.

CXF has been supporting WADL since 2.2.3. The auto-generated WADL instances can describe live RESTful services quite well, with JAXB-generated schemas being included in WADL grammar elements and indeed with all the subresources being described too, as long as the static subresource resolution is enabled.

More enhancements have to and will be done but first I'll touch on what I call a WADL dilemma.

It is a Web Application Description Language. It is the way it describes the *Web application* that distinguishes it. For example, a WADL consumer such as a RESTful client test framework can read a given WADL document and let users test the application by following the application paths described by WADL.

I think it's of little doubt that the decision has been made to design WADL such that application interfaces (such as Person or Book, etc) could not be described in WADL. This is absolutely normal given that RESTful consumers are generally programming againt generic HTTP interfaces and programming with proxies is often considered to be an antipattern. Thus I guess adding the possibility to describe application interfaces was an obvious non-starter.

As a side note, before proceeding further, I think I might be nearly coming to the conclusion, that as far as choosing between proxies or http-centric clients for consuming restful services is concerned, it is really like choosing between different shades of grey. Some users, when they see proxies, think RPC immediately but it is not quite the case for proxies producing perfectly valid RESTful requests. Neither option is immune to the service changes though but good frameworks such as CXF will offer a lot of help for coping with such changes. I think it may be more a matter of the taste these days...

So back to the dilemma. What I think is currently missing from WADL is the fact it can not be used to generate what seems to be the main source of auto-generated WADL instances : JAX-RS annotated service classes. The WADL-first option will work well for the http-centric consumers but it is Java-first all the way for the JAX-RS services.

The Java-first approach to the services development has proved to be very popular and viable. However, the option of modeling web resources and generating service classes seems quite attractive too but enhancing WADL to support such an option would just basically turn it into WSDL. And this is where the dilemma is.

In meantime, a number of various approaches is being tried to create richer WADLs out of Java classes. One of those attempts is to do with extracting Java Docs for resource classes and methods and publishing them as WADL documentation fragments - it does seem like a step too far given that Java Docs are meant for the Java engineers using a given interface or class. But not for the users of Web Services backed up by such classes/interfaces.

In CXF we've added a Description annotation which is mapped to a WADL doc element and we will recommend users to use this annotation for documenting resources or methods using the language intended for the users of a given web service.

The other thing we need to think about is how we can let users do the WADL first developement. The question is how to avoid turning it into WSDL. That said, we should also probably look closer at the option of supporting WSDL2, especially for the users who do both SOAP and REST - having a single document describing both SOAP and REST may benefit them, though as far as describing RESTful services is concerned WSDL2 seems a bit limited.

Stay tuned.