WADL stands for Web Application Description Language. It is a member submission to the W3C by Sun Microsystems (now Oracle), written by Marc Hadley (now at MITRE). WADL is to REST as WSDL is to SOAP, which interestingly enough, makes it both a useful documentation and code generation tool for RESTful web service development, and anathema to the RESTful in-crowd (of which, I'm apparently not a member). I'd also note that you can use WSDL for the same purpose (which is apparently even worse).
WADL isn't a standard, but it was certainly meant to fill a gap in standards for RESTful web services. I've been playing around with WADL a bit to define and document the ABBI protocol. What I found useful about WADL is that it makes me think about (and document) all the necessary aspects of services that an implementer needs. The advantages of using WADL are pretty significant. I can get a lot of documentation out of WADL that would be difficult to create in the same way using a word processor.
There are several tools available that will take a WADL description and turn it into documentation of a RESTful API, others that will turn it into code, and yet others that will generate WADL from code. All-in-all, useful stuff when you have a small team (as I do). Sure, I don't need any tools to do this by hand, but why not use them if they make my job easier. One of the things I like about WADL is that it helps me to order my thinking, and to make it easier to understand the API. I can still read the XML and understand what it is doing.
One of my experiments in playing with WADL was to restructure the OAuth 2.0 RFC in WADL form, since we are also talking about using OAuth 2.0 for ABBI. OAuth 2.0 doesn't define the resource URLs, it just defines what they need to do, which makes them a <resource_type> in WADL instead of a <resource> proper. The tool I was using to generate documentation didn't support <resource_type> so I fixed it to do so (and made some other tweaks to it).
I haven't finished documenting either the ABBI API or the OAuth 2.0 specification in WADL, but the results are promising enough that I've posted them both to my prototype implementation site. You can find them at the links above.
Ignoring the technical issues and my opinion, the source of the controversy is easily answer by asking "cui bono".
ReplyDeleteWADL is asking some developers to do tedious extra work, spend extra time, maybe spend extra money, for no apparent benefit. Of course they don't want to do it.
The first time you learn anything new, it is harder, more difficult and time consuming to do it the new way than the old. However, as you get better at it, it might just save you (or your customers and partners) time. After three days, I've already passed the break-even point.
Delete