openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

I'm totally for everything you said. Versioning should absolutely be separate from the code. That is exactly what I was pushing for in my original proposal. I was planning on continuing the discussion w.r.t. how to expose these versions after we agree on the actual structure of the versions themselves. I was also going to suggest we only expose the major version number in the URI since it should always be backwards compatible. We do need to communicate the minor/revno at some point, however, so clients who expect the latest version can be sure they have it. For the time being, I would like us to focus on agreement around the api versioning scheme itself. This needs to happen before we can agree on conventions specific to the spec the version applies to.

Waldon


On Oct 10, 2011, at 12:55 PM, Bryan Taylor wrote:

> I think we should separate versioning APIs from code. Client needs should drive API versioning.
> 
> Generally, I agree we should focus versioning on backwards compatibility and feature sets, but REST is supposed to be media type centric, so I'd like to see separate versioning around data formats that doesn't associate it with a versioned URI structure.
> 
> Basically, if a data format stays the same feature wise, you shouldn't break clients by telling them it has a new version because of the OpenStack release, when the format itself didn't change. The commons, mixed deployments, and alternative implementations all will make this quite complex if we don't get on top of it soon.
> 
> Generally things visible to API clients at runtime should only expose the major version number which changes ONLY when non-backwards compatible changes happen. Artifacts visible to clients at design time should expose a major and minor version so developers can give a name to a feature set of that artifact.
> 
> So I'd version items as follows:
> Package - major.minor.release of the code
> WADL - version by major.minor of its OpenStack release
> URI - version by major version of the corresponding WADL
> Media type - version by major version of the data type
> XSD - version by major.minor of the data type
> XML Namespace - version by major version of the data type
> JSON docs - major.minor of the data type
> 
> On 10/10/2011 08:55 AM, 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.
> 
> 
> _______________________________________________
> 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