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 :)
