I've seen some comment out there regarding how to version RESTful services and so thought it about time to add in my own position on this.
I don't subscribe to crafting your own MIME type as these should refer to well-known entities. I also don't subscribe to passing a version number as an Accept param. Despite there being client/server compatibilities in this regard (Ruby), the developer is not forced to specify the version. I think it is useful to specify the version of a service to use.
I'm an advocate of using a /v1 path in the url of a RESTful service, but it should be noted that great care should be taken in exactly what that version number refers to. I've long subscribed to the major.minor[.maintenance[-build]] approach as per Maven and reasonably discussed at Wikipedia. In the case of URL versioning, only the major identification is used i.e. "1.0.2" becomes just "v1".
Major versions only change when there is an API-breaking change that has been introduced. This should be very rare. API-breaking generally means quite a big shift in the approach an API is taking which is why I found it interesting that Google declare their Google Maps API will always be backwardly compatible. To me that's effectively what held Microsoft back with Windows until Vista came along and started to drop backwards compatibility (Windows 7 of course is the evolution of that good decision).
So I say use /v[major] as a convention, but be diligent in the definition of what is "major".
1 comment:
Stu Charlton summarizes the various options available for versioning RESTful services which he prefaces by saying “These can be tricky concepts to describe, and I don't really want to write a small book on this topic”. He categorizes the versioning problem into two types; Data Versioning, which aims to version the resource itself so tracking changes to state of any given resource becomes possible; and Language Versioning which refers to the protocol itself; in other words the representation.Restaurant Software
Post a Comment