openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

Thanks for the feedback, Mark! Comments inline:

On Oct 11, 2011, at 9:51 AM, Mark McLoughlin wrote:

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

This is exactly where I stand. Supporting each minor version has already proven to be a pain, so I would love to *only* support the latest, and the easiest way to communicate this is to use the major version in the URI.

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

I think there are two key things here:

1) I think we need to look at Nova as a feature of OpenStack. We version *that* independently from the rest of the suite.

2) We have the concept of extensions (which can be versioned independently from the spec) that provide non-standard functionality through the API. This is how we add optional features within Nova.

> 
> 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
> 
> 
> This email may include confidential information. If you received it in error, please delete it.



--------------------------------------
Brian Waldon
Cloud Software Developer
Rackspace Hosting