[openstack-dev] [Ironic] Let's talk about API versions

Devananda van der Veen devananda.vdv at gmail.com
Sat Aug 1 00:18:48 UTC 2015


It sounds like we all agree -- the client we ship should default to a
fixed, older version. Anyone who wants newer functionality can pass a newer
version to their client.

Here's the current state of things:

server:
- stable/kilo: 1.6
- current: 1.11

client:
- stable/kilo: 1.6
- latest release (0.7.0): 1.6
- current: 1.9

So -- since we haven't released a client that sends a header > 1.6, I
propose that we set the client back to sending the 1.6 header right away.
While having the client default to 1.1 would be ideal, this should still
keep the "Jackson the Absent" of the world as happy as reasonably possible
moving forward without breaking anyone that is packaging Kilo already.

(yes, this may affect Olivia the Contributor, but that's OK because Olivia
will have read this email :) )

-Deva


On Fri, Jul 31, 2015 at 2:50 PM Jim Rollenhagen <jim at jimrollenhagen.com>
wrote:

> On Fri, Jul 31, 2015 at 02:37:52PM -0700, Clint Byrum wrote:
> > Excerpts from Sean Dague's message of 2015-07-31 04:14:54 -0700:
> > > On 07/30/2015 04:58 PM, Devananda van der Veen wrote:
> > > <snip>
> > > >     Thoughts?
> > > >
> > > >     * I'm assuming it is possible to make micro version changes to
> the
> > > >     1.x API
> > > >       as 1.10.1, 1.10.2,etc
> > > >
> > > >
> > > > Despite most folks calling this "microversions", I have been trying
> to
> > > > simply call this "API version negotiation".
> > > >
> > > > To your question, no -- the implementations by Nova and Ironic, and
> the
> > > > proposal that the API-WG has drafted [1], do not actually support
> > > > MAJOR.MINOR.PATCH semantics.
> > > >
> > > > It has been implemented as a combination of an HTTP request to
> > > > "http(s)://<server URL>/<major>/<resource URI>" plus a
> > > > header "X-OpenStack-<service>-API-Version: <major>.<minor>".
> > > >
> > > > The <major> version number is duplicated in both the URI and the
> header,
> > > > though Ironic will error if they do not match. Also, there is no
> <patch>
> > > > or <micro> version.
> > > >
> > > > So, were we to change the <major> version in the header, I would
> expect
> > > > that we also change it in the URL, which means registering a new
> > > > endpoint with Keystone, and, well, all of that.
> > >
> > > Right, it's important to realize that the microversion mechanism is not
> > > semver, intentionally. It's inspired by HTTP content negotiation, as
> > > Deva said. I wrote up a lot of the rational for the model in Nova here,
> > > which the Ironic model is based off of -
> > > https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/
> > >
> >
> > Thanks Sean, this post was exactly what I needed to understand the
> > inspiration behind the current situation.
> >
> > > Ironic is a little different. It's entirely an admin API. And most
> users
> > > are going to only talk to an Ironic that they own the deployment
> > > schedule on. So the multi cloud that you don't own concern might not be
> > > there. But, it would also be confusing to all users if Ironic goes down
> > > a different path with microversions, and still calls it the same thing.
> > >
> >
> > I think being single-tenant makes the impact of changes different,
> > however the solution can be the same. While tools that use Ironic may
> > not be out in the wild as much from an operator perspective, there will
> > be plenty of tools built to the Ironic API that will want to be
> > distributed to users of various versions of Ironic.
> >
> > It sounds to me like for Ironic, the same assumption should be made as
> > in the outlined "Jackson the Absent" solution. Assume no version is old
> > version, and require specifying the new version to get any new behavior.
> >
> > What is preventing Ironic from embracing that?
>
> So, this is actually how the Ironic API behaves. However, it was at some
> point decided that the client should have a more recent default version
> (which is the main topic for this thread).
>
> I agree with you; I think this is the best route.
>
> // jim
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150801/b9de6b8d/attachment.html>


More information about the OpenStack-dev mailing list