REST Describe and Compile

Thomas Steiner has released version 0.3 of his REST Describe & Compile tool, which creates a WADL description from existing REST messages, and can then in turn generate code for multiple languages. The new version adds support for generating Java code (in addition to PHP, Ruby, Python and C#). To get a first impression of what REST Describe & Compile does, check out the online version; you can also download the source code, which is written in Java using Google Web Toolkit.

Thomas joined InfoQ for a quick Q&A email session to answer some of the most obvious questions about the approach and tooling.

InfoQ: Can you give us the brief elevator pitch - the 10 second introduction - to REST Describe & Compile?

Thomas Steiner (TS): WADL is for REST what WSDL is for SOAP. WSDL has Axis and WSDL2Java, REST has REST Describe & Compile which is a cool WADL generating tool, and WADL2Anything. Kind of ;-)

InfoQ: What’s the association with Google?

TS: It is a Final Year Project hosted by Google, but not an official Google product. I have been working as a temporary contractor for Google during my studies, and recently signed a full-time contract with start date in October.

InfoQ: Do you intend the on-the-fly creation of a service description something that I’d use once to work in a contract-first style afterwards?

TS: Having the URI structure in mind, you can create your service in an “example-driven” way. And get the code as well as the WADL description for free. All you need is a set of examples of future requests your web service will support, run the tool over them and out comes the WADL and the client-side code in whatever language you need it.

InfoQ: What’s your reply to arguments that code generation is evil?

TS:

/**
* This file has been auto-generated by REST Compile.
* You should not modify it, unless you know what you do. Any modification
* might cause serious damage, or even destroy your computer.
*/

Besides this, code generation allows you to very quickly react on contract changes. You modify your service description, run the code generator, and there you go. Code generation allows for complete consistency, maintenance gets a lot easier as you just have to maintain the generator, and not single files. It is pretty much like making love. You can only talk about it once you have enjoyed it.

InfoQ: What’s your opinion about the ongoing debate about whether REST needs a description language?

TS: To be honest, I think there is too much fuss around what is REST, and what only RESTful, and what is WS-* in REST camouflage. I think the question is not about how HTTP methods map to CRUD and questions like that which people have been discussing for a long time now. I am more on Nelson Minar’s side: “Just do something that works”. There is not a REST way to do things, there are company ways to do things. And sometimes one company gets bought by another, so suddenly there are two company ways. Just have a look at Yahoo!, Flickr, and Del.icio.us. All these APIs are great, and indeed work very well. Some APIs require no authentication at all, others force HTTP AUTH, and most services have some kind of a token parameter. The problem is that there is no common machine-readable way to document this. WADL may be close to a WSDL-ish way to describe a service, but who cares? The spec is about 14 pages long, you can read it, even understand it, and, yeah, actually implement it. There is a WADL to HTML tool by Marc Nottingham, there are Marc Hadley’s (and now SUN’s) WADL tools, and finally there is REST Describe & Compile. Maybe WADL is not the silver bullet of web services, but it does a very solid job. It let’s you do whatever you want, be it pure REST, be it POX, be it somewhat RESTful, or just something that works.

InfoQ: What plans do you have in store for future versions?

TS: At present the application runs completely on the client side. This has a lot of advantages, however, in the long term limits its powers. There might be a live WADL2Anything service one day, where people send there WADL requests to, and get code back. People should be given the possibility to save their WADLs online, for others to access for free. Something like CDDB for web services. This are more the visionary plans, there are more basic goals to accomplish first: improve the ability of code generation, add XML schema support, improve syntax-highlighting, add more and more languages to the REST Compile module,…

InfoQ: Thanks!