RESTful Versioning

I commented on RESTful versioning as a response to Peter William’s post on the same subject matter as I found it interesting. Because versioning is a fact of life and we can’t avoid it even though Subbu thinks we should, it’s imperative to always architect services with versioning in mind. Now that I’ve pondered over this a little bit, I think I get why getting this right is extremely important.

Part of architecting for versioning includes talking to potential (or existing) customers and figuring out what input/output of the service should look like. Never architect without involving the customer base. Having said this, it’s highly unlikely that the inputs/outputs will never change. Change is inevitable and this is why there must be a very good versioning solution.

Right now there seems to be two proposed ways of supporting versioning: via URIs and through the use of custom media types. When the client is the human web, URIs are really the only option. It’s with the programmable web that there may appear to be a decision to be made.

The Programmable Web

With the programmable web, choosing between the using Accept header and custom media types versus a URI becomes a little more interesting because of “hypermedia as the engine of application state” (HATEOAS). Consider the base representation of a resource with a URI of “http://order/123” that contains links to other resources.





Now imagine that the resources evolve independently of each other, such that there is a version 3 of “order” and a version 2 of “orderLine” yet the resources remain linked. From a programmable angle, if the the service uses a URI versioning scheme (http://v1/order/123), the service provider probably tries to ensure that the representations always contains the URIs for the right versions of its linked resources. It would probably be fair to assume that version 2 of order links with version 2 of orderLine but that is assuming that the resources actually evolve together which may not be case. Additionally, what if a consumer has evolved to version 3 of order but is still satisfied with version of 1 orderLine and cares for no other version? The service provider falls into the trap of trying to anticipate the versions of resources that a consumer wants. This almost impossible to pull off in a system that evolves – and most every system evolves.

With custom media types, the client is responsible for specifying the version of every single resource that they want. The service provider is not burdened with trying to figure out what version of application state a client will try to navigate. It defers that decision to client. It only needs to know how handle version requests. The client could ask version 3 of order by doing this:

Accept: application/vnd.mycompany.myapp-order-v3+xml

and for version 2 of orderLine, doing this:

Accept: application/vnd.mycompany.myapp-orderLine-v2+xml

A good versioning solution should allow the client to specify what version of a service/resource they want to reference at any given time.

Versioning in RESTful systems needs to be done outside of the URI if the system is to evolve and allow its clients to evolve with it. URI versioning doesn’t seem to be much of an option, am I mistaken?


Versioning RESTful Web Services

Peter Lacey Williams posts here and here on how to version RESTful Web Services using custom MIME media types and I find this very interesting. I do find the following quote about the browser a little curious:

They (browsers) are almost certainly not the target consumer of the services

If your web applications are RESTful in nature, then the browser is definitely the target consumer of them. So I’m not sure if Peter is suggesting that with services that return HTML as a content type, there aren’t versioning issues or that services that would face versioning issues generally do not use HTML as a content type.

Should Architects Code?

I chuckle whenever I hear or read the question “should architects code”. Joe brings this up again in the Rabbit Hole and I promised to blog about this at some point. Well it’s over a week later and I think I finally have some time to put something brief down.

The short answer to the question is yes. But answering yes leads to another question and that is: what should an architect code? To answer this question, one has to identify what an architect actually does. To keep things simple, let’s just assume that an architect is responsible for the architecture of a system. What then is architecture?

Architecture and Architectural Styles

A definition for architecture states that architecture (and it’s specifications) are both intensional and non-local meaning that software architecture concerns itself with abstractions that are:

  • applicable in multiple domains
  • applicable at a system level

Hence architects talk and discuss things like Rest-Oriented Architecture, Service-Oriented Architecture, Event-Driven Architecture, Layered Architecture etc. Code they write should be focused on illustrating these architectures and architectural styles. Being able to think abstractly is suppose to come with years of designing and implementing systems.  This is not always the case for everyone.

This is not intended to suggest that an architect should not write code that demonstrates design principles or is actual implementation code. That is dependent on an organizations structure.  However, if  you are an architect and you’re in a situation where you are not writing any code at all, simply put, “check yourself!”.