On 12/12/2012 01:10 AM, 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.
If have any concerns about this approach, please speak up.
Thanks,
Richard
This gets a +1 from me.
Thanks Richard.
