WADL - Or Maybe Not

I have changed my mind on thinking that WADL Gateway Drug.

Dare Obasanjo has a great post on it. It pushed me over the edge.

If it was the only way to convince someone to not go the WS-* route, I'd go for it. But too much madness can result from it and it is just much simpler to avoid this for now anyway.

Here was the clincher for me from Dare's post:

Another word that is often abused in the SOAP/WS-* world is contract. When I think of a contract, I think of some lengthy document drafted by a lawyer that spells out in excruciating detail how two parties interact and what their responsibilities are. When a SOAP/WS-* developer uses the word contract and WSDL interchangeably, this seems incorrect because a WSDL is simply the XML version of OMG IDL. And an IDL is simply a list of API signatures. It doesn't describe expected message exchange patterns, required authentication methods, message traffic limits, quality of service guarantees, or even pre and post conditions for the various method calls. You usually find this information in the documentation and/or in the actual business contract one signed with the Web service provider. A WADL document for the REST Web service will not change this fact.

WADL Gateway Drug

Stefan Tilkov responds to Aristotle Pagaltzis who thinks REST doesn't need a service description language:

In principle, I agree; for pragmatic reasons, I believe efforts like WADL make sense, if only to have an answer to one of the most obvious questions for new REST converts :-)

+1 to that.

Take a gander at the spec. I tear up just looking at it. It is beautiful compared to WSDL - just beautiful.

I think that the risk with any service description language is that people take it too far and become overly dependent on it. Generating code from them tends to do this. But then again, code gen can be helpful. You just have to know when you have taken something too far and not be afraid to press the eject button to dumb it back down.

I think that REST client developers at the very least will want schema definitions of what to expect in request/response payloads. IMHO WADL does a good job of not taking things too far. As I said, compared to WSDL it is a thing of beauty. It is so simple when the only option is HTTP (i.e., compared to the absolute insanity of protocol agnosticism).

If you aren't going to use WADL, you are going to have to document the service in prose or some such. WADL at the very least seems to be a really concise way to document things.

Update Somebody should give Mark Baker a trophy or something. I still will take WADL any day over WSDL, but Mark is probably right. Still, I'll take baby steps if that is what it takes.

Update 07-JUN-2007 I have been convinced that a service definition language is not good idea right now.