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

Clint Byrum clint at fewbar.com
Thu Jul 30 17:16:17 UTC 2015

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

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.


* I'm assuming it is possible to make micro version changes to the 1.x API
  as 1.10.1, 1.10.2,etc

More information about the OpenStack-dev mailing list