Generate Code from your WADL REST API Descriptions with REST Describe & Compile

By Thomas Steiner. Written on Wed May 23 2007. Work

Generate Code from your WADL REST API Descriptions with REST Describe & Compile

The first comment by britneyfreek on Dion Almaer's blog post on Ajaxian.com on REST Describe from some weeks ago is a little questioning:

"this is rather cool and actually useful, isn't it? […]"

With today's v0.2 release of REST Describe & Compile I hope that some more people will respond to this comment with yes, it is. The new version allows for

WADL creation based on sample request(s)
WADL editing using an advanced interactive editor
Code generation based on a WADL file which may be
- either created by REST Describe based on sample request(s),
- or uploaded from an external source into REST Describe

At present code generation is limited to PHP, however, the architecture is completely modular so that generators can be easily added. For the next release it is planned to support Java, Python, Ruby, and C# (currently the corresponding buttons are grayed out). In the following I will describe the changes and new features in some more detail:

Recommended reading before getting started: WADL spec, REST Describe v0.1 release note, introduction to REST Compile by ProgrammableWeb.com

WADL feature support almost complete

The new version has almost complete feature support for WADL. In the REST Describe WADL editor the degree of freedom has greatly increased which means that a lot of hard-wired code from the last release has been generalized. Now you can modify your WADL file completely interactively, with context-sensitive behavior of the editor. For example <param> elements adapt their available features depending on their parent node, and each object let's you just add the particularly allowed sub-objects. This helps you create valid WADLs. The idea of the editor is to mix the properties of a syntax-highlighted XML file, a tree, and all this enriched by WADL-specific features like the type estimation with a custom types manager.

WADL Parser allows for editing of existing descriptions

The more WADL will gain interest with RESTafarians, the more WADL files will get written. The v0.2 parsing feature allows you to upload any WADL out there in this crazy world, edit it in the REST Describe application, or even create code from it. When you check out WADL uploading be sure to give the del.icio.us WADL a try (it is hard-coded as a demo in the WADL Upload dialog, you need to adapt the version available on the referenced web site). Once you hit the OK button the file gets parsed, a tree gets created, and then you can play with the file, create code from it, or even save it and then upload it again (this was my test to see whether the parsing feature worked). Parsed files will show up in fullscreen mode, but of course you can easily leave this mode if you feel like.

More RESTful behavior

Even if most REST APIs are somewhat not completely REST (e.g. you place all your requests to one endpoint and a parameter contains the actual operation), there are a lot of others that actually are RESTful. REST Describe now lets you choose the HTTP method that should be used for the request. This is not a big change, however an important one. Thanks to Jan Schulz-Hofen for his reminder (see his comment [Yeah] on my v0.1 release blog entry).

Code Generation, or what I call REST Compile

By definition a "compiler is a computer program that translates a computer program written in one computer language […] into an equivalent program written in another computer language". I take this definition a little sloppy and replace the first "computer program" by a "service description", and the "equivalent" by "implementing this service", and even if this does not really result in an English phrase, you probably got the idea. Once you have a WADL, implementation in a programming language is just a localization problem. Wait a minute. Did I write localization problem? Yes, because this is basically what the code generation feature in REST Compile is based on (thanks for the localization joke, Pat). The application is created with Google Web Toolkit, and the toolkit's I18N Message feature which is based on Java property files provides us with a certain kind of template functionality. How does this work? Let's start with an explanation of the feature the way it was thought (i.e. for I18N):

You start with a template in each language:
runningOutOfDiskSpace = Caution, you only have {0} left.
runningOutOfDiskSpace = Achtung, Sie haben nur noch {0} übrig.

At runtime the program inserts the actual amount of available disk space, and only the strings that need to be localized are kept in the property file. Now back to the code generation idea. For instance functions or methods or whatever you want to call them exist in almost every programming language. There are slight differences, however, the main idea is the same. Have a look at two equivalent functions, the first in Ruby and the second in PHP:



def welcome(name)

   puts "howdy #{name}"

end



function welcome($name) {

   echo "howdy" . $name;

}

So "}" becomes "end", "def" becomes "function" and so on. For each language there are characteristic structures, only the dynamic content needs to be updated. What REST Compile does is that a CodeGenerator fabric class loads for example a PHP5Generator class which then loads its particular Templates_PHP.properties file. In consequence if you want to add another language, simply register your generator in the CodeGenerator factory, write your template file, add your dynamic code generating stuff to the generator, and there you go. By the way: this I18N message abuse allows code generation to happen completely on the client side. You could download the whole application and run it offline.

Getting started

The source code is available under a BSD license. You can also check out the application directly in your browser. Therefore you might want to bookmark a link to the latest version of REST Describe & Compile. It is also available in German. Looking forward to hearing back from you. If you happen to be around Barcelona, Spain on June 27th - 29th, Patrick Chanezon and me will be co-presenting on TheServerSide.com Java Symposium. REST Describe & Compile will cover the second part of the presentation.

WADL is a great REST description language. You have done an awesome job, Marc! Hopefully other developers will pick up on this release, and make WADL the REST description language. Even if I would have named it differently, though ;-)

Yes, I do work for and get paid by Google for working on this project, but no, the project is not an official Google product. Period.