On Tue, Dec 11, 2012 at 05:10:51PM -0800, Richard Su wrote: > 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_and_Versioning > >>> > >>>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.
+1 > > If have any concerns about this approach, please speak up. > > Thanks, > > Richard -- Petr Blaho, [email protected] Software Engineer, CloudForms
