[openstack-dev] [Nova] Some thoughts on API microversions

Edward Leafe ed at leafe.com
Thu Aug 4 15:28:23 UTC 2016

On Aug 4, 2016, at 8:18 AM, Andrew Laski <andrew at lascii.com> wrote:

> This gets to the point I'm trying to make. We don't guarantee old
> behavior in all cases at which point users can no longer rely on
> microversions to signal non breaking changes. And where we do guarantee
> old behavior sometimes we do it artificially because the only signal we
> have is microversions and that's the contract we're trying to adhere to.

I've always understood microversions to be a way to prevent breaking an automated tool when we change either the input or output of our API. Its benefit was less clear for the case of adding a new API, since there is no chance of breaking something that would never call it. We also accept that a bug fix doesn't require a microversion bump, as users should *never* be expecting a 5xx response, so not only does fixing that not need a bump, but such fixes can be backported to affect all microversions.

The idea that by specifying a distinct microversion would somehow guarantee an immutable behavior, though, is simply not the case. We discussed this at length at the midcycle regarding the dropping of the nova-network code; once that's dropped, there won't be any way to get that behavior no matter what microversion you specify. It's gone. We signal this with deprecation notices, release notes, etc., and it's up to individuals to move away from using that behavior during this deprecation period. A new microversion will never help anyone who doesn't follow these signals.

In the case that triggered this thread [0], the change was completely on the server side of things; no change to either the request or response of the API. It simply allowed a failed resize to be recovered more easily. That's a behavior change, not an API change, and frankly, I can't imagine anyone who would ever *want* the old behavior of leaving an instance in an error state. To me, that's not very different than fixing a 5xx response, as it is correcting an error on the server side.

So if you haven't guessed by now, I agree with Andrew that microversions are not the best choice for signaling all changes. I'm not sure that adding either of the things he proposed would address the issue in [0], though.

[0] http://lists.openstack.org/pipermail/openstack-dev/2016-August/100606.html

-- Ed Leafe

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 842 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160804/165152d8/attachment.pgp>

More information about the OpenStack-dev mailing list