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@lists.launchpad.net >> 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 _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
