Open Stack

On May 10, 2011, at 5:52 PM, Jay Pipes wrote:

> Hey all,
> 
> We've been working to improve the Glance API. The first step to
> improving the API, however, is to add versioning to it.
> 
> We've gotten a lot of the work done on this versioning of the API (see
> https://code.launchpad.net/~jaypipes/glance/api-version/+merge/60130).
> 
> However, there is an issue that remains unresolved that we would like
> some community input on.
> 
> We have a choice of using the following two API URIs:
> 
> /v1/images
> /v1.0/images
> 
> I coded the latter (/v1.0/images) because I was copying the way that
> swauth and Nova's OpenStack API do it, but Brian Waldon brought up the
> fact that major versions of APIs should never break clients written to
> that major version of the API, so there is no real reason to specify
> the minor version in the URLs.

Whether or not you use a .0  at the end of the URI version is at your digression -- it may still be useful to have it denote that the API hasn't changed radically from one version to the next.  Thus the 1.1 compute API has only minor additions and subtractions but no dramatic changes.  That said, in Rackspace, we consider the entire version in the URI (v1.0, v1.1) a major version number -- I know that's confusing.   There's nothing saying you can't start with v1 and move to v1.5  or v2 if need be.   The important thing to consider is that the whole things is  major version number.

We do use minor version numbers for other aspects of the service.  Here are the rules that we're considering at least internally at Rackspace:

WADLs  major and minor version number, minor revision changes are backward compatible.
XSD major and minor version numbers, with minor revisions denoting backward compatible changes.
Media Types -- major number only
XML Namespaces -- major number only
Version URIs -- major number only

Backward compatible changes with the Media Type, the XML Namespace, and the Version URI always fall within the same major version number.  There's really no benefit, for example,  in having a separate URI if we have backward compatible changes.

> I would prefer the shorter /v1/images API, myself.


This is what we're considering at Rackspace as a standard :-)  Fair warning though, there may be non-technical (i.e. marketing) reasons for using a pseudo-minor version number in the future.

-jOrGe W.



Confidentiality Notice: This e-mail message (including any attached or
embedded documents) is intended for the exclusive and confidential use of the
individual or entity to which this message is addressed, and unless otherwise
expressly indicated, is confidential and privileged information of Rackspace.
Any dissemination, distribution or copying of the enclosed material is prohibited.
If you receive this transmission in error, please notify us immediately by e-mail
at abuse at rackspace.com, and delete the original message.
Your cooperation is appreciated.