RFC: API versioning

Petr Blaho pblaho at redhat.com
Mon Dec 17 09:49:23 UTC 2012


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, pblaho at redhat.com
Software Engineer, CloudForms


More information about the aeolus-devel mailing list