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

Jim Rollenhagen jim at jimrollenhagen.com
Mon Jul 27 20:35:25 UTC 2015

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.

Our API versioning scheme makes this opt-in (by specifying the API
version). However, some folks have a problem with releasing this change
as-is. The logic is that we might release a client that defaults to 1.11
or higher, or the user may request 1.12 later to get a new feature, thus
breaking their application that enrolls nodes.

This is clearly backwards. Users should read release notes and be aware
of what changes between versions in the API. Users need to be aware of
the fact that our API is versioned, and use that to their advantage.

It seems to me that the goal of the version negotiation in our client
has been to pretend that our API versions don't exist, from a user
perspective. We need to stop doing this and force users to think about
what they are doing when they interact with our API.

It seems to me we have a few options here:

1) Default the python client and CLI to the earliest supported version.
This will never break users by default.

2) Default the python client and CLI to use the special version
'latest'. This will always use the latest API version, and always
break people when a new server version (that is not backwards
compatible) is deployed.

3) Do what Nova does[1]. Default CLI to latest and python client to
earliest. This assumes that CLI is typically used for one-time commands
(and it isn't a big deal if we break a one-off command once), and the
python client is used for applications.

4) Require a version to use the client at all. This would be a one-time
break with how applications initialize the client (perhaps we could fall
back to the earliest version or something for a deprecation period).
This isn't a great user experience, however, it's the best way to get
users to think about versioning. And no, "this requires typing another
argument every time!" is not a valid argument against this; we already
require a number of arguments, anyone sane doesn't type --ironic-api-url
or --os-username every time they use the client.

5) Do what we're doing now. Bump the client's default version with every
release. This mostly hides these versions from end users, and in general
those users probably won't know they exist. And then we run into
arguments every time we want to make a breaking change to the API. :)

I think I like option 1 or 3 the best. I certainly don't like option 5
because we're going to break users every time we release a new client.

What do other folks think we should do?

// jim

[0] https://github.com/openstack/ironic/commit/1410e59228c3835cfc4f89db1ec482137a3cfa10
[1] http://specs.openstack.org/openstack/nova-specs/specs/liberty/approved/novaclient-api-microversions.html

More information about the OpenStack-dev mailing list