[openstack-dev] [Ironic] Let's talk about API versions
chris.friesen at windriver.com
Thu Jul 30 15:57:21 UTC 2015
On 07/30/2015 12:55 AM, Michael Davies wrote:
> On Tue, Jul 28, 2015 at 6:05 AM, Jim Rollenhagen <jim at jimrollenhagen.com
> <mailto:jim at jimrollenhagen.com>> wrote:
> 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. 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
> 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?
It seems to me that this is basically microversions except that it gives you the
added knowledge that a backwards incompatible change has occurred. I'm not
quite clear how that makes any difference though.
For applications linking against libraries, the major version implies a
dependency--the application requires that specific major version of the library,
and a minor version at least as good as what it was built against. How would
that translate to a REST API? Would the client code need to special-case every
major version that they plan on supporting? What about minor versions that add
functionality--if we special-case those as well then we're basically back to
More information about the OpenStack-dev