openstack team mailing list archive

[Mark McLoughlin <markmc@xxxxxxxxxx>]

Hi Brian,

I think the versioning rules below are fine, but there are some other
things to think about:

 - As others raised, what version (if any) should be in the URIs?

   We could put the full version number in the URIs so long as we
   maintain support for the older, compatible versions i.e. the current 
   version is 1.5.3 but clients can still use the 1.4.0, 1.5.2 etc. URIs

   The only problem I see with that is that it might appear like 
   clients connecting to the 1.4.0 URI should expect only the features 
   that were available in 1.4.0.

   If we're not going to make it so new features are only exposed to 
   clients requesting the new version, then just including the major
   version number in the URI is probably the most sane.

 - Version numbers aren't necessarily the best way to advertise the 
   availability of features - if we made clients query for the 
   availability of the features they're using, you could version the 
   features independently.

   For example, if we decide we must make an incompatible change to some
   obscure feature, wouldn't it be nice to version the feature rather
   than bump the major version of the API.

   Also, it allows the API to have optional features that not all 
   service providers support.

   In the API for RHEV-M/oVirt, we went for this approach - all 
   collections are discoverable by link relationships and, if we must 
   make incompatible changes, we will version those relationships.

Cheers,
Mark.

On Mon, 2011-10-10 at 09:55 -0400, Brian Waldon wrote:
> In talking with several people at the Design Summit about the
> OpenStack Compute API, I have come to the conclusion that our current
> method of versioning is broken. I would like to propose that as we
> move forward, we adopt the following API versioning conventions:
> 
> 1) Use a three-part version number: A.B.C, where A is the major
> version, B is the minor version, and C is the revision number.
> 
> 2) Disallow backwards incompatible changes to existing interfaces
> within a major version. This means we cannot rename something such
> as /servers to /interfaces, or remove the resize action from a server.
> 
> 3) Increment the minor version at OpenStack releases (Cactus, Diablo,
> Essex, etc). This is used to indicate the 'regrouping' period around
> the time of release. It doesn't offer much functionality other than to
> provide a nice round number that can be easily communicated and used
> to group features together.
> 
> 4) Increment the revision number with every addition to the API
> interface. This allows consumers of the API to get a precise list of
> supported features at any given time. This also allows operators to
> continuously deploy the API between major releases and know exactly
> what featureset they have. When the minor version is increased, we
> reset the revision number to 0.
> 
> I would assume that if we do agree on these conventions, they would
> only be a suggestion, not a requirement. I really want to get this
> right, so I'm looking forward to everybody's feedback!
> 
> Thanks!
> Brian Waldon 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp