openstack team mailing list archive

[Bryan Taylor <btaylor@xxxxxxxxxxxxx>]

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.