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

GHANSHYAM MANN ghanshyammann at gmail.com
Fri Jun 26 00:46:17 UTC 2015

On Thu, Jun 25, 2015 at 5:18 PM, Ken'ichi Ohmichi <ken1ohmichi at gmail.com> wrote:
> 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.

This is really nice point. We should give power to users to decide whether they
need/want to use/get the new features introduced in new microversion
of it is backward compatible or not.

> Current microversion implementation of Nova is blocking this situation
> by making backwards every compatible change appear on each
> microversion.
> 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.
> Thanks
> Ken Ohmichi
> ---
> [1]: https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Thanks & Regards
Ghanshyam Mann

More information about the OpenStack-dev mailing list