RFC: API versioning

Martin Povolny mpovolny at redhat.com
Tue Dec 18 08:37:56 UTC 2012


On Mon, Dec 17, 2012 at 10:49:23AM +0100, Petr Blaho wrote:
> 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.
> >

I think that the assumption that we are able to maintain backwards
compatibility from an early development stage of the API is overly
optimistic.

I would suggest moving that obligation into the future. At this point I
would see as much more important to get the API right and if we find out in
February that we have done some poor design decision in the API I would suggest
rather fixing it than keeping the backward compatibility.

Furthermore I think that there's no way to say if the API is good until
we have some API client that actually uses the API.

The new CLI being probably the first consumer of the API I would expect
issues to show up while developing the CLI.

So to wrap up I would suggest postponing the idea of maintaining
backward compatibility in the API to the point when we actually have a
working CLI.

Happy hacking!

-- 
Martin Povolny <mpovolny at redhat.com>
tel. +420777714458


More information about the aeolus-devel mailing list