[occi-wg] Versioning RESTful Services v2 | Howard Dierking

[Sill, Alan]

Thought you would be interested in the blog post at the following link, having to do with principles for API versioning

Topic:
Since publishing both the REST Fundamentals course as well as my previous post on RESTful API versioning, I%u2019ve had the opportunity to think more about versioning in practice as I've been a part of designing the next major revision to the NuGet API (v3). This has been very helpful for a couple of reasons, but the most important one is that NuGet is a real application that has both non-trivial scale requirements and a number of different clients %u2013 many of which are not controlled by the NuGet core team. Going through this API design exercise has both validated some of my earlier thinking as well as revised some other thinking. The point of this post is to lay some of that out.
... (content of the article here) ...
[So] I’ll add another principle (well, borrowed it from Fielding actually):

all important resources must have URIs

This ends up impacting versioning strategies as follows:

	• If you’re adding only, go ahead and just add it to the representation. Your clients should ignore what they don’t understand
	• If you’re making a breaking change to the representation or changing the meaning of the underlying resource, create a new resource with a new name (URI)
	• Use content negotiation in such a way that it can provide an optimized path to resources, but always give the client control (by way of links) to make different choices

Link:
http://codebetter.com/howarddierking/2013/09/12/versioning-restful-services-v2/

Opinions welcome.

Best regards,
Alan