[openstack-dev] [api][nova][ironic] Microversion API HTTP header

Sean Dague sean at dague.net
Tue Jun 16 13:07:51 UTC 2015

On 06/16/2015 08:38 AM, Lucas Alvares Gomes wrote:
> Hi
>>> So if our min_version is 2.1 and the max_version is 2.50. That means
>>> alternative implementations need implement all the 50 versions
>>> api...that sounds pain...
>> Yes, it's pain, but it's no different than someone who is following the
>> Amazon EC2 API, which cuts releases at a regular (sometimes every 2-3 weeks)
>> clip.
>> In Amazon-land, the releases are date-based, instead of
>> microversion/incrementing version-based, but the idea is essentially the
>> same.
> Sorry I might be missing something. I don't think one thing justify
> the other, plus the problem seems to be the source of truth. I thought
> that the idea of big tent in OpenStack was to not having TC to "pick
> winners". E.g, If someone wants to have an alternative implementation
> of the Baremetal service they will always have to follow Ironic's API?
> That's unfair, cause they will always be behind and mostly likely
> won't weight much on the decisions of the API.
> As I mentioned in the other reply, I find it difficult to talk about
> alternative implementations while we do not decouple the API
> definition level from the implementation level. If we want alternative
> implementations to be a real competitor we need to have a sorta of
> program in OpenStack that will be responsible for delivering a
> reference API for each type of project (Baremetal, Compute, Identity,
> and so on...).

I kind of feel like we've sprung up a completely unrelated conversation
about what big tent means under a pretty narrow question about 'what
should this header be called, and if/when should we change it now that
it's in the field'. I've probably contributed to it drifting off topic
as well.

However, I think it would be good to try to focus on the topic at hand
which is header naming, what the implications are, and if/when changes
should happen.

The goal of Microversions was crisping up the API contract to the user
across multiple deploys, at different points in time, of the *same*
upstream codebase. That's the narrow problem we are trying to fix. It's
not a grandious API abstraction. It might let us get to one down the
road, now that we can evolve the API one bit at a time. But that's a
down the road thing.

So in that context we have a current header which references a service
by code name.

The plus side of that is we've already got a central registry for what
that should be, openstack/{name}.

Also the problem with expanding to generic names is with Neutron you get
OpenStack-Network-API-Version but there are multiple network
implementations still. Or even worse, what if Congress and or GBP
implement microversions? OpenStack-Policy-API-Version? What about
projects that start off outside of openstack/ and implement this kind of
mechanism, so either don't have a moniker, or land grab one that we're
not comfortable with them having inside of OpenStack.

So I don't think it's clear that in the general case the generic moniker
is better than the code name one. And it's a change to a thing in the
field, so I feel like deciding on that kind of change is probably a
thing we need to make sure we really think the change will be beneficial
to our stake holders, API consumers, Operators, Developers, Integrators.

On a change like this I'd much rather not preoptimize for out of tree
re-implementations, which I think we've said pretty strongly at a TC
level that we don't want, and instead leave the status quo until there
is a strong reason that benefits once of our stake holders.


Sean Dague

More information about the OpenStack-dev mailing list