RFC: API versioning

Martyn Taylor mtaylor at redhat.com
Fri Nov 30 14:23:08 UTC 2012


On 11/30/2012 01:43 PM, Jiří Stránský wrote:
> On 29.11.2012 00:12, Richard Su wrote:
>> Hi,
>>
>> I'm going to start the discussion on versioning. After some research, 
>> a question that I think we should be asking first is does the API 
>> need to be versioned at all? Or what do we mean by versioning?
>>
>> I think there are two initial paths. Do we build the API so that it 
>> is backwards compatible so that existing clients continue to work as 
>> the api evolves in future conductor releases? Or is this not tenable 
>> and we should prepare for the inevitable change that will break 
>> backwards compatibility and introduce a versioning scheme?
>>
>> * Backwards Compatibilty
>>
>> Leaving discussions about Heat and CIMI aside (which look to be 
>> layers on top of a base Conductor API) and if we think our existing 
>> models are correct and are stable I think maintaining backwards 
>> compatibillity would be the simplest course. This means that once 
>> we've released an API, changes should be additive; removing 
>> attributes or elements is not allowed. It also means we never remove 
>> ways of interacting with the API. If we add a new field to a 
>> resource, to maintain compatibility with existing clients it should 
>> be possible to create the resource without specifying the new field.
>>
>> We would indicate the version of the API in a header so that the 
>> client knows which version it is taking to. And changes to the API 
>> will be documented as each version if released. But there is no 
>> effort here to make multiple versions of the API available through a 
>> HTTP header or URI off of the same Conductor instance.
>>
>> * Versioning
>>
>> A while ago we committed to having the API work off the same 
>> controller as the UI. If we decide that the API must be versioned, I 
>> think we will need to break the API off to its own controllers.
>>
>>  From what I have gathered, most versioning schemes use a namespace 
>> to denote a version and each namespace has its own controllers, 
>> views, and tests. A new API version would mean copying the current 
>> namespace/version into a new directory with its own controllers, 
>> view, and tests. There are some gems like Versionist or Rocket Pants 
>> to ease versioning. What is not clear to me though is if there is a 
>> significant modeling change how would one make different versions of 
>> the API continue to work off of the same Conductor instance.
>>
>> Is there a particular requirement that requires us to version the 
>> API? I think there will be significant work involved if we do choose 
>> to version the API. Is it worth the effort?
>>
>> Or is there some other type of versioning people are thinking about?
>>
>> Your thoughts?
>
> We already know we can't keep compatibility with API that's now in 
> use. When Tim comes, the image management API will change. One could 
> say we will have a "v2 API" in place. And we won't provide backwards 
> compatibility or let the client choose which API version it wants to 
> use. Letting my mind wonder into the hypothetical future - Conductor 
> can develop in a way that we can have this "v2 API" in place for some 
> (hopefully a long) time, but eventually we might have to change the 
> API again into "v3 API".
>
> So, my 2 cents: I don't want to serve multiple API versions from one 
> Conductor instance, I want to stick to backwards compatibility as much 
> as possible, but I'd like to provide version information with the API 
> and have clients indicate what version they expect to communicate 
> with. When we absolutely have to make changes (hopefully once in a few 
> years), we make them all at once and increment the API version.
>
> In an ideal world, we would stick to being backwards compatible like 
> CIMI or Deltacloud, but I don't think this is possible for Conductor, 
> given the amount of evolution. Also we would have to be much, much 
> more careful about introducing new fields in API than we are right now 
> ... which we should be anyway :) (Thinking of the discussion about 
> deployables #show we are having, which also applies to instances API. 
> I'm sorry I didn't make the time to go through the API RFC properly 
> and raise my objections earlier.)
>
> Take care,
>
> J.
This gets a +1 from me.  We do not* want to support multiple versions of 
the API in the foreseeable future.  Our API is too unstable right now.  
Once we have a stable API then we can think about it, possibly having 
some support period for the previous version.  Until then though, I 
think a general policy amongst the team of trying to maintain backwards 
compatibility as much as possible and having a way to determine the API 
version should be sufficient.  The version in the entry point URL v 
Content Type gets my vote.

Thanks

Martyn
>
>>
>> ------
>> Resources I found useful:
>>
>> 1. http://watzmann.net/blog/2012/08/rest-api-evolution.html
>> 2. http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown
>> 3. 
>> http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#Compatibility_and_Versioning
>>
>> 4. http://railscasts.com/episodes/350-rest-api-versioning
>





More information about the aeolus-devel mailing list