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

Michael Davies michael at the-davies.net
Thu Jul 30 06:55:10 UTC 2015

On Tue, Jul 28, 2015 at 6:05 AM, Jim Rollenhagen <jim at jimrollenhagen.com>

> [snip]
> 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?

Thanks jroll for bringing this up!

Isn't the problem here that we're treating breaking and non-breaking
changes similarly?

Didn't we previously say that major backward incompatible changes should
require a major version bump?

What if we adopted a semver or similar scheme for API versioning?  What if
we required 'Major' (in Major.Minor.Patch) to increment for a backwards
incompatible change?  In our current tooling this would be hard, but is it
what we should be doing?  Is this the root of the problem?

I think we want the latest version of the API, used by the client and
server, that is backwards compatible i.e. min(latest client version, latest
server version).  As developers we want the latest version of our code out
there.  As operators and users we want the latest (backward compatible)
features and the bug fixes, but we don't want to rewrite how we interface
to the software.

But if a version is explicitly specified, that should be used instead i.e.
we should support version pining so that operators can gracefully upgrade
when it's right for them (assuming the server still supports that version)

But the question remains, "What version of the API do we want to ship when
we ship a major Ironic release?" (whenever that is now[1] :-P ) Or phrased
differently, "How do we advance versions from release to release?".  I
think the answer to this is that we default to the latest stable major API
version at the point of release.  That should be the default for client and
server, and shouldn't discount anyone from using older clients with newer
servers and vice versa due to the presence of version negotiation.

Hope this helps,


Michael Davies   michael at the-davies.net
Rackspace Cloud Builders Australia
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150730/0adcd5b3/attachment.html>

More information about the OpenStack-dev mailing list