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

Jim Rollenhagen jim at jimrollenhagen.com
Fri Jul 31 21:47:12 UTC 2015


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



More information about the OpenStack-dev mailing list