When I came across the WADL spec 6 months or so ago, it seemed to me that it was reaching for desirable goals. I’ve done a number of integration projects using SOAP, a few involving more ad-hoc XML-over-HTTP designs, and even a couple recently that more consciously strive to be REST-ful. Through those experiences, one of the things that I have liked about SOAP is that one can exchange a WSDL file with another organization and get server-to-server integrations moving along pretty quickly. Furthermore, if you’re used to reading WSDLs and the author wrote it sensibly, you can get a precise understanding of what data is going on the wire, and generally what’s involved in using a service in a shorter time than poring through prose documentation. Maybe it’s some form of software Stockholm Syndrome, but I’ve grown to like the ol’ WSDL. The larger WS-* family of hydra-headed standards gives me the same headaches that it gives others, but I do think that it’s nice to be able to hand over a machine-processable description of your system’s API interface which enables remote clients implemented in nearly any programming language on any OS to access its functionality.

So on the basis of recently re-reading the WADL spec and writing a couple of test WADL documents, I’m pretty confident in saying that WADL has at least achieved the basic goal of applying the WSDL concept to the REST service world. On top of that, the spec is lucid, succinct and highly readable — it’s like poetry compared to any of the WS-* specs.

There is a fair amount of criticism of the WADL effort from the RESTafarian camp, but none of it actually takes the spec to task for being poorly done. Rather, the criticism seems to center around the idea that the whole notion of a formal description language for REST applications is misguided from inception. Some of the highlights of that criticism come from Aristotle Pagaltzis, Mark Baker and Dare Obasanjo.

I think Aristotle’s remarks are perhaps the most valid — maybe a different sort of specification (along the lines of the ATOM Pub. spec) is needed to go whole-hog with the REST approach. But on the other hand, I’m willing to bet that 95% of the people who turn their nose up at using something like WADL will then turn around and write their plain old human readable documentation in such a way that it describes exactly the same things that WADL describes: what URLs to hit, what parameters to pass, what data to expect in return, etc. Because so far that’s what I’ve seen in APIs such as the ones offered by Flickr, Facebook, etc. To my mind, having a succinct, easily machine-processable form of documentation for your code seems like a win.