Open Stack

The really ugly but most formal way to change an API like this is to do a double-deprecation over three releases:

  1. introduce the new version in a temporary home and deprecate the old one in release #1.
  2. remove the old version in release #2 and replace it with the new version. Deprecate the temporary home for the new version.
  3. remove the deprecated temporary home for the new version in release #3, leaving you with just the new version at its proper home.

That said, the much faster option is to document it as a backwards-incompatible change, make the official clients handle both versions with a hack, and apologize to the people who you break things for.

I vote for the latter, and consider it the cost of bringing all the project APIs into line.

    - Gabriel

> -----Original Message-----
> From: Dean Troyer [mailto:dtroyer at gmail.com]
> Sent: Tuesday, January 29, 2013 3:59 PM
> To: OpenStack Development Mailing List
> Subject: Re: [openstack-dev] [keystone] endpoint versioning in API v3
> 
> On Tue, Jan 29, 2013 at 1:48 PM, Jay Pipes <jaypipes at gmail.com> wrote:
> >>Is the keystone-client expected to know the response format? Do you
> > expect the version information returned by "swift" same as that of
> "compute"
> >
> > Good question. It would be awesome if OpenStack projects that publish
> > a public API would standardize on the results returned by a call to
> > the API endpoint's root URI (the one that should return a 300 Multiple
> > Choice with the version information).
> 
> Keystone appears to be the outlier here, nova, cinder and glance all return a
> list of version structures like:
> 
> { "versions": [ { ... }, ] }
> 
> where keystone's looks like:
> 
> { "versions": { "values": [ { ... }, ] } }
> 
> I'm trying to think of a way to change that without breaking things.
> How do we version the version discovery API?   It's trivial to change
> keystoneclient, but that still breaks all of the other language bindings that
> actually use it.
> 
> Swift returns a 404.  I didn't have an operational Quantum API available to
> check it.
> 
> dt
> 
> --
> 
> Dean Troyer
> dtroyer at gmail.com
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev