On 11/30/2012 06:23 AM, Martyn Taylor wrote:
> 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