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.
------
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
