REST Describe first working Beta released

By Thomas Steiner. Written on Thu Apr 26 2007. Work

REST Describe first working Beta released

Today I have released version 0.1 of REST Describe (described in an earlier blog post). The application is based on the idea that creating a description for a Web Service should be a rather simple task given the information already contained in requests. Let's take a very simple imaginary online bookmarking Web Service to make the idea clear:

GET http://bookmarks-online.com/api/v1/bookmarks?userId=tom&tags=rest&limit=10

Simply by looking at the URI we can extract the following information:

http://bookmarks-online.com: there is a Web Service at this base address.
/api/v1/: this is the path to access the service components.
bookmarks: there is an operation that manages your bookmarks.
?userId=tom&tags=rest&limit=10: it takes three arguments, "userId", "tags", and "limit". When we have a closer look, we could guess that "userId" and "tags" are both strings, and that "limit" is an integer value.

And all this information just from one example request. This is basically what the REST Describe approach is based on. It takes an (ideally complete) list of URIs, analyzes the structure, does some type estimations, and afterwards creates an XML representation of the request. Marc Hadley has done a great job in defining WADL, the XML-based Web Service description language REST Describe supports.

However, the approach described above has some shortcomings:

Custom types cannot be guessed (e.g. searchOptions = {all | phrase | any}). In a sample request there would be just a parameter value "phrase" for example. To any analyzer this looks perfectly like a string, there is no way to find out that the only valid values are "all", "phrase", and "any". That is why REST Describe allows for custom type definition
Repeating or required parameters cannot be determined. The pure presence of a certain parameter does not automatically imply that this parameter is necessary or not. Thus REST Describe allows for completely interactive WADL editing. You can create, remove, or modify almost everything directly in the WADL tree.
Type estimation is a sometimes tricky job. Imagine we have a parameter value of "1". This might be an integer value, however, very often this is also used as a boolean value. What REST Describe does is to analyze the parameter name and the parameter value as well. How does this work in real life? It is common programming practice to prefix boolean parameters with "is", for example "isActive". This is a first clue that "1" might be a boolean in a parameter "isActivated=1", and a string in "results=1". Adjectives terminate very often with "ed", so a parameter "enabled=1" might be a boolean, too. This kind of type analysis allows REST Describe to give the user an idea of how exact the type analysis is.

REST Describe is developed with the Google Web Toolkit. During development I very often hit the limit of available event management memory and after a few test runs had to restart the hosted Google Web Toolkit Browser. However, besides this annoyance, the toolkit is a real pleasure to use. It allows for completely Java-fied web application development. There are some problems with Trees in ScrollPanels, I hope that with the next release of the toolkit these issues will be resolved.

Click here to check out REST Describe directly in your browser, if you want even in German. In addition to that, the full source code is available under the Apache 2.0 license. Hope you like the release. Feedback and bug reports are warmly welcomed. Please do not hesitate to contact me directly. My contact data are available on this blog.

Update: In order to avoid any confusion I have changed the name of the project, basically I have removed the "Google" from it. Yes, I do work for and get paid by Google for developing this project, but no, the project is not an official Google product. Period.

Please note: REST Describe and REST Compile are no official Google products.