Open Stack

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/

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.

Fwiw, we just landed our "when do you need a microversion" document
which might also ad context here -
http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion

	-Sean

-- 
Sean Dague
http://dague.net