<div dir="ltr"><br><div class="gmail_quote"><div dir="ltr">On Thu, Jul 30, 2015 at 10:21 AM Clint Byrum <<a href="mailto:clint@fewbar.com" target="_blank">clint@fewbar.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Excerpts from Jim Rollenhagen's message of 2015-07-27 13:35:25 -0700:<br>
> Hi friends.<br>
><br>
> Ironic implemented API "micro" versions in Kilo. We originally did this<br>
> to allow for breaking changes in the API while allowing users to opt in<br>
> to the breakage.<br>
><br>
> Since then, we've had a "default version" for our client that we bump to<br>
> something sensible with each release. Currently it is at 1.8.<br>
> Negotiation is done with the server to figure out what is supported and<br>
> adjust accordingly.<br>
><br>
> Now we've landed a patch[0] with a new version (1.11) that is not<br>
> backward compatible. It causes newly added Node objects to begin life in<br>
> the ENROLL state, rather than AVAILABLE. This is a good thing, and<br>
> people should want this! However, it is a breaking change. Automation<br>
> that adds nodes to Ironic will need to do different things after the<br>
> node-create call.<br>
><br>
<br>
Great discussion. I think through this thread I've gained some insight<br>
into what is going on, and I think the problem is that minor version<br>
bumps are not for backward incompatible changes. As a user, I want to<br>
pin everything and move the pins after I've tested and adapted with new<br>
versions of things. However, I also don't want to have to micro manage<br>
this process while I move forward on different schedules with my REST<br>
clients and the Ironic service.<br>
<br>
So, to be clear, I may have missed what you're trying to do with micro<br>
versions.<br>
<br>
In my world, a 1.10 -> 1.11 would be for adding new methods, new<br>
arguments, or deprecating (but not removing) an existing piece of the<br>
API. But changing the semantics of an existing thing is a major version<br>
bump. So I wonder if the right thing to do is to bump to 2.0, make the<br>
default in the client 1.10* for now, with deprecation warnings that the<br>
major version will not be assumed for future client libraries, and move<br>
on with the understanding that micro versions aren't supposed to break<br>
users of a particular major version.<br>
<br>
Thoughts?<br>
<br>
* I'm assuming it is possible to make micro version changes to the 1.x API<br>
  as 1.10.1, 1.10.2,etc<br><br></blockquote><div><br></div>Despite most folks calling this "microversions", I have been trying to simply call this "API version negotiation". </div><div class="gmail_quote"><br></div><div class="gmail_quote">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.<br></div><div class="gmail_quote"><div><br></div><div>It has been implemented as a combination of an HTTP request to "http(s)://<server URL>/<major>/<resource URI>" <span style="line-height:1.5;font-size:13.1999998092651px">plus a header</span><span style="line-height:1.5;font-size:13.1999998092651px"> "X-OpenStack-<service>-API-Version: <major>.<minor>". </span></div><div><br></div><div>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.<div><br></div><div>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.</div><div><br></div><div>-D</div><div><br></div>[1] <a href="https://review.openstack.org/#/c/187112/">https://review.openstack.org/#/c/187112/</a></div><div> </div></div></div>