[Openstack] OpenStack API Versioning Conventions

Mark Nottingham mnot at mnot.net
Tue Oct 11 05:26:24 UTC 2011


Where would these versions show up? In URLs? In documentation? In response payloads?

If they show up in URLs, then every backwards-compatible change would be made into a backwards-incompatible change. E.g., if you had

http://www.example.com/v1.2.3/foo

as a resource, and adding a new resource .../bar bumps it to v1.2.4, then that backwards-compatible change (because it doesn't break old clients) now causes everybody to break. 

The only sensible thing to put in URIs is a major version identifier that indicates backwards-incompatible changes (i.e., the slate is wiped clean, it's a different URL tree). E.g.,

  http://www.example.com/v1/

Of course, that can be any arbitrary string, whether it be "v1" or "v1.1" or "essex". However, putting "v1.1" in there is going to confuse people, because most people believe that a minor release is, by nature, backwards compatible.

If we want to just use them in documentation, there's no harm, of course. Likewise, the client could query the server to find out what it supports, but something more descriptive than a linear version number would be useful; e.g., some sort of linked capability catalogue format.

Cheers,



On 11/10/2011, at 12: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 at lists.launchpad.net
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

--
Mark Nottingham   http://www.mnot.net/







More information about the Openstack mailing list