Bill the Plumber

I was thinking alot about REST and service versioning again today.  In my previous blog I talked a bit about using the media type and probably XML schema to guarantee a contract between the client and server.  The client would ask for “application/vnd1+xml” and be all set for its conversation to begin.

The big problem I see with this is a service maintenance problem.  As you rev your service and your schema you’re going to have to support a lot of different media types.  What would make things easier is if XML Schema supported polymorphism.  That way a client could ask for “application/vnd1+xml” format and still receive and validate a newer version of the schema.  Please correct me if I’m wrong, but I don’t think you can do this in XML schema.  Yes you could extend various types from the parent to create a newer version of a schema, but a validator would not be able to enforce a polymorphic relationship with its parent AFAIK.

Clients and servers could get around this XSD problem by not doing validation and hoping that the schema developers are disciplined enough to make future versions of the format backward compatible.  It just seems incomplete to me to not be able to validate.

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.