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