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_a...
>>
>> 4.
http://railscasts.com/episodes/350-rest-api-versioning
>
To wrap up this discussion, the conclusion here is that we will maintain
backwards compatibility and not support multiple versions of the API in
the same Conductor instance. We will embed a version number so that
clients can determine which version of the API they are speaking to.
If have any concerns about this approach, please speak up.
Thanks,
Richard