I was reading recently a very excellent article by Subbu about Describing RESTFul Applications.  I highly recommend the article as it very clearly illustrates the RESTful principle of HATEOAS.  One of the profound questions the article asks is does REST need a description language like IDL or WSDL? I guess the main arguments for this would be:

  • Tooling.  Would be nice to be able to generate some client and server code to avoid all the boilerplate nonsense you usually have to do.
  • Define an enforceable contract that can be validated.

There is something called WADL out there, but, as Subbu sort of hints at in his article, such an approach encourages an RPC-like approach for defining interactions with your application.  He goes on to describe what he feels like might be a good definition language while, at the end, asking the question of: Is it Practical? with the biggest roadblock being:

How about software tools that want to test or enforce the contract? It is possible to create such software that reads the above machine-readable description to do the following at runtime.

  • Check that the media types of representations are predefined.
  • Check that the representations match the predefined descriptions of media types.
  • Check that all links contained in representations have predefined relations and media types, and that the URIs included follow predefined URI patterns.

I am not aware of any software that can validate these in this manner.

My answer to this question and roadblock is, why not have your media type define your entire contract?  Require that certain links and relations be a part of your document and define them explicitly in your XSD.  Maybe even the atom link’s media type should be required as well.  Then, simple XML validation can guarantee the contract.  The client application locks in the contract simply by specifying an Accept header containing a custom media type with its initial URI traversal.  We still get a lot of decoupling because the endpoint URIs are discovered at runtime yet we have something we can both generate code from and enforce a contract through.  Add in URI Templates to your links and all you’re missing is what HTTP methods are allowed to be invoked.  Using schema to enforce your contract doesn’t have to stop at XML as mappings like BadgerFish and tools like Jettison have shown.

All and all, the more I think about it, the more I believe that Human Documentation plus a schema is all that is needed in the RESTful world.  I’m glad that as more people like Subbu think and analyze through the IDL problem there are less and less reasons to have an IDL for REST.