BT

REST Describe and Compile

by Stefan Tilkov on Jun 07, 2007 |

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!

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Is code generation of interface code sensible? by Frank Carver

Within the context of the software being discussed (REST Describe and Compile), the suggestions in the article seem to make sense. What I'm not sure I understand is why the code being generated needs to exist in the first place. Let's disregard for the moment the issue of automatic versus manual generation of such code, and consider the purpose of the code itself.

I assume that for code to be automatically generated, it must not contain any application-specific business functionality. Presumably the job of the code being generated is solely marshalling, unmarshalling generic format conversion and so on. If this is not the case, and then I'd love to be enlightened.

If this is the case, then any change to REST parameters, URL, body or response content will imply one of two things for the application: either (a) some business code will need to change in order to supply new or changed operations or data and to deal with new or changed responses, or (b) no business code will need to change because it does not make use of the facilities which have changed.

In case (a) the most effective development approach would be to change only the business logic. In case (b), the most effective development approach would be to not change the application at all. In neither case would spending time to change or regenerate interface code be of benefit to the overall business solution.

So, if the code in question has no business-specific value, then we should question the need for the code at all. In particular, we should consider it a candidate for abstraction into a generic solution which does not need to change when the interface changes. Ideally a general solution could be found for which only the calling business code need change, and only when the business needs change.

This is not just a theoretical principle. I habitually "consume" WS-* web services without recourse to code generation from WSDL or any other interface definition. I have wrapped Apache Axis with some generic code which allows a call sequence such as:


SOAPCaller caller = new SOAPCaller(baseURL);
...
Object response = caller.call(serviceName, methodName, arg, ...);


The SOAPCaller class is completely generic, and has been reused for several different applications against completely different sets of web services.

For REST, the same approach applies, but is even simpler to implement. Pretty much every language comes with libraries which can make a HTTP request to a specified URL, passing in and recieving body text if necessary. What else is needed?

To summarize my point: if the code being generated can be abstracted into a reusable component, why would generating it each time an interface changes make any sense?

Re: Is code generation of interface code sensible? by Viktor Lieskovsky

To summarize my point: if the code being generated can be abstracted into a reusable component, why would generating it each time an interface changes make any sense?


I agree with this, for dynamic languages this truly makes sense. Abstract it all to a reusable class, supply it with the WADL or whatever, and there you go. For Java/C#, things are bit different. You get more when you have your boileplate code generated by the tool. What you get is that the compiler enforces you to use correct types of arguments when calling these 'remote' methods, and you get code-completion, which can be very handy for APIs you are not familiar with.

The need for code generation by Elisha Ezeugoh

I'd say code generation in this case could serve the purpose of a -by-example approach to would-be callers of the web application. So when viewed in that light alone, I think its a great idea.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

3 Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT