Presenting a RESTful web service

Lately I've been pondering on how to create a unambigious description for the RESTful web service I am designing. The kink is to create a description that will work both ways: For consumbers AND producers. In addition it should be easy to maintain and develop.

So I figured that there is a description language called WADL - Web Application Description Language. Suitable for REST they say. Great indeed, but as it is not a formal standard, there are very few tools supporting the format. I.e. neither MagicDraw nor XmlSpy supports designing a service, Microsoft Visual Studio doesn't seem to support. For Java, there's wadl2java, which generates the services proxies. But still there's no design tool.

GlassFish and maven-wadl-plugin can reverse engineer your annotations, and create a WADL describing your service. If you implemented it with JAX-RW. My service was already tentatively implemented using Spring Web, so no luck.

A lot of services offered "in the cloud", or as we said previously "on the Internet", have textual descriptions for their APIs. Such services include Google Search API, Twitter, Flickr, Sun Kenai etc. But textual descriptions can be ambigious if not carefully written, expecially when it comes to describing message exchange formats. For message consumers, this is probably a reasonable tradeoff. But having several producers, this would most certainly lead to ambigious services.

So, my solution was to 1) describe the services/resources as text in the API document, and 2) describe the resource models/message formats using XSD. XSD have wide tooling support. This takes us where we want to be.

The next step would be to hand-craft the WADL using the generated XSDs, but I'll leave that as an excercise to the reader :)

Twitter programming session

Last night I had a live programming session with ~30 CS students at the University of Oslo. The goal was to show how easy it is to interact with RESTful webservices in Java. I started out with explaining about HTTP and Jersey, REST vs SOAP, JSON vs XML and jsonlib vs jaxb. Those were the major design decisions.

I subsequently implemented a bot that would befriend anyone that was following the bot. Doing this with jsonlib was pretty straightforward, but showed the weakness of not having a higher level abstraction of the domain. Therefore, the next bot would get status updates from his friends timeline, and show them in a simple GUI. This proved a lot smoother when jaxb was at work, because it created two separate layers: one interacting with twitter restful webservices, and another showing model objects in the GUI. Last I showed a bot that used twitters search api to follow a trending topic.

Overall it was a good session, but I think it was a little bit too packed with technology choices. I guess it would have been of greater value to just show the magic of jaxb, and skip the primitive alternative.

The javabots is available for download at http://bit.ly/FyeqT for a while.