While poring over versioning issues on RESTful web services i stumbled upon Peter Williams post proposing the use of vendor MIME media types to get the versioning under control. I really like this idea because it is simple and fits tightly to the REST approach. But trying to apply his approach in reality some difficulties came up.

Basically, carry along the version in the URL seems not very RESTful to me. First, it bloats your URL (well, not much but it does) and second if the version of resource change, it does not mean that its location changes as well. In opposite it has to be constant!

To get around this, Peter outlines the concept of custom vendor MIME media types which are enriched by an API version number and changing if the version changes. Great idea! Seems to fit - but wait … He assumes that one has defined his own exchange protocol for ressource representation and manipulation. If so everything goes well. But how about using standard formats? Why? Think about abandoning the hassles with defining an own exchange protocol or your new API and simply wed a standard like the Atom Publishing Protocol (APP) and the REST approach. Since the APP has his own MIME type you can not easily change by enriching it with versioning numbers. Doing so would result in loss of core benefits you wanted to take advantage of: Rely on a growing library of components supporting Atom development in almost any major scripting or programming language while spending less time developing core data exchange functionality - simply because the header is not understood anymore. In my opinion in such a case it may be useful to define a custom X-Header to carry your versioning informations. The question is: How RESTful is this approach? ;). For me it is a tradeoff and i am going to use it to see how thing behave this way.

In the comments Peter states that he is aware of the discrepancy with the standard formats and already thinks about a solution which he is going to publish.

By the way: He also outlines the downsides of his approach and provides some ways to migrate the negative impacts.

I’m looking forward to an interesting discussion.

Best,
Frank