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