Open Stack

On Thu, Jul 30, 2015 at 10:21 AM Clint Byrum <clint at fewbar.com> wrote:

> Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700:
> > Hi friends.
> >
> > Ironic implemented API "micro" versions in Kilo. We originally did this
> > to allow for breaking changes in the API while allowing users to opt in
> > to the breakage.
> >
> > Since then, we've had a "default version" for our client that we bump to
> > something sensible with each release. Currently it is at 1.8.
> > Negotiation is done with the server to figure out what is supported and
> > adjust accordingly.
> >
> > Now we've landed a patch[0] with a new version (1.11) that is not
> > backward compatible. It causes newly added Node objects to begin life in
> > the ENROLL state, rather than AVAILABLE. This is a good thing, and
> > people should want this! However, it is a breaking change. Automation
> > that adds nodes to Ironic will need to do different things after the
> > node-create call.
> >
>
> Great discussion. I think through this thread I've gained some insight
> into what is going on, and I think the problem is that minor version
> bumps are not for backward incompatible changes. As a user, I want to
> pin everything and move the pins after I've tested and adapted with new
> versions of things. However, I also don't want to have to micro manage
> this process while I move forward on different schedules with my REST
> clients and the Ironic service.
>
> So, to be clear, I may have missed what you're trying to do with micro
> versions.
>
> In my world, a 1.10 -> 1.11 would be for adding new methods, new
> arguments, or deprecating (but not removing) an existing piece of the
> API. But changing the semantics of an existing thing is a major version
> bump. So I wonder if the right thing to do is to bump to 2.0, make the
> default in the client 1.10* for now, with deprecation warnings that the
> major version will not be assumed for future client libraries, and move
> on with the understanding that micro versions aren't supposed to break
> users of a particular major version.
>
> 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.

-D

[1] https://review.openstack.org/#/c/187112/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150730/1fb4cdfb/attachment.html>