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