[openstack-dev] [api] [Nova] [Ironic] [Magnum] Microversion guideline in API-WG

Ken'ichi Ohmichi ken1ohmichi at gmail.com
Thu Jun 25 08:18:59 UTC 2015

Sorry for late response here,

2015-06-20 9:14 GMT+09:00 Devananda van der Veen <devananda.vdv at gmail.com>:
> Long version...
> Every HTTP response from Ironic today includes three headers: min, max, and
> version. The service can present an older API version, as long as it is
> greater-than-or-equal-to the minimum supported version, even if that version
> is incompatible with the maximum supported version.  It does this by
> rewriting responses to match what was expected in the requested (older)
> version.
> When the newer version is identical *for all interfaces present* in the
> older version, this can be called compatible. Dmitry's point is that we
> don't need to hide newer interfaces from users who request an older API
> version, because the client won't know or care about things that weren't in
> the version it requested.
> However, we *do* need to signal their presence, and we don't have a good
> means for that right now. We also need to signal to the client that the
> response given is "compatible with" a certain "age" of API, even if it's not
> exactly the same. And we don't have any means for that, either.
> Time for an example....
> Let's say that an incompatible change was made in v1.3. Let's also say that
> a change was made in v1.5 that added a new endpoint. Today, this is what the
> response headers would look like when calling a server running v1.5.
> a) client requests v1.2, receives headers (min: 1.1, max: 1.5, current: 1.2)
> b) client requests v1.4, receives headers (min: 1.1, max: 1.5, current 1.4)
> c) client requests v1.5, receives headers (min: 1.1, max: 1.5, current: 1.5)
> What we have implemented today is that in case (b), the service will *hide*
> any changes that we introduced in v1.5. But those changes did not affect any
> functionality of the v1.4 API, so Dmitry objects to this. So do I.
> The issue at hand is the response in case (b) ... though after spending the
> last several months working on api versioning, I actually think all of those
> are poor responses.
> What I believe we should have:
> a) client requests v1.2, receives headers (min: 1.1, max: 1.5,
> compatible-with: 1.1)
> b) client requests v1.4, receives headers  (min: 1.1, max: 1.5,
> compatible-with: 1.3)
> b) client requests v1.5, receives headers  (min: 1.1, max: 1.5,
> compatible-with: 1.3)
> Yes -- (b) and (c) are identical responses.
> Discuss.

I think it is good that backwards compatible changes(new features) are
available on older microversion also *only* if the clouds which are
used by users continue upgrading.

I think Sophia's role on "The Backwards Compatibility Fallacy" of
Sean's blog[1] has answered to this question, but I'd like to try
explaining it here for considering Ironic situation.
As the example, there are multiple public clouds which provide
different max microversions like:

Cloud A: Max microversion: v1.5
Cloud B: Max microversion: v1.1

A user wrote his own application for running on cloud A and specifying
v1.1 on the first application implementation.
The first application used small number of APIs, and he wanted to
extend the application.
If all backwards compatible changes(v1.2 - v1.5) appear on lower
microversion(in this case v1.1), he can use all new features even if
specifying v1.1.
That seemed really great for users at this time, and he extended the
application for using all features as possible.
but the specified microversion still is v1.1 because his application
worked fine even if using newer features.

After that, he needed to switch to the other cloud because of cost
merit or something.
The specified microversion was v1.1, so he did think his application
can work fine on cloud B also because of cloud B's max microversion.
But yes, his application could not work because his application had
already used newer features which are implemented on v1.2+.
In the real world, there are a lot of clouds and it is easy to imagine
this situation.

Current microversion implementation of Nova is blocking this situation
by making backwards every compatible change appear on each
Nova team needs to consider interoperability between clouds so well
because Nova API is one of general external interfaces for end users.

On the other hand, Ironic API is for administrators, not for end users.
I am imaging that:
* Some administrator wrote his application for using Ironic API.
* From the viewpoint of administrator, the switching destination cloud
in newer in most cases.
* The application can continue working on newer clouds even after
switching many times.

So I feel the above interoperable issue example would not happen on
Ironic in most cases unless hiding backwards compatible changes on
lower microversion.
I guess this is the difference between Nova and Ironic on
interoperability discussion.

I cannot/don't want to enforce Ironic way at all, and it's fine to
find the best way on each project as OSS projects.
But only my concern here is that we cannot use "Microversions" as a
perfect keyword for OpenStack interoperability on whole OpenStack
projects if Ironic goes to the other way.

Ken Ohmichi

[1]: https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/

More information about the OpenStack-dev mailing list