Open Stack

I've brought some of these thoughts up a few times in conversations
where the Nova team is trying to decide if a particular change warrants
a microversion. I'm sure I've annoyed some people by this point because
it wasn't germane to those discussions. So I'll lay this out in it's own
thread.

I am a fan of microversions. I think they work wonderfully to express
when a resource representation changes, or when different data is
required in a request. This allows clients to make the same request
across multiple clouds and expect the exact same response format,
assuming those clouds support that particular microversion. I also think
they work well to express that a new resource is available. However I do
think think they have some shortcomings in expressing that a resource
has been removed. But in short I think microversions work great for
expressing that there have been changes to the structure and format of
the API.

I think microversions are being overused as a signal for other types of
changes in the API because they are the only tool we have available. The
most recent example is a proposal to allow the revert_resize API call to
work when a resizing instance ends up in an error state. I consider
microversions to be problematic for changes like that because we end up
in one of two situations:

1. The microversion is a signal that the API now supports this action,
but users can perform the action at any microversion. What this really
indicates is that the deployment being queried has upgraded to a certain
point and has a new capability. The structure and format of the API have
not changed so an API microversion is the wrong tool here. And the
expected use of a microversion, in my opinion, is to demarcate that the
API is now different at this particular point.

2. The microversion is a signal that the API now supports this action,
and users are restricted to using it only on or after that microversion.
In many cases this is an artificial constraint placed just to satisfy
the expectation that the API does not change before the microversion.
But the reality is that if the API change was exposed to every
microversion it does not affect the ability I lauded above of a client
being able to send the same request and receive the same response from
disparate clouds. In other words exposing the new action for all
microversions does not affect the interoperability story of Nova which
is the real use case for microversions. I do recognize that the
situation may be more nuanced and constraining the action to specific
microversions may be necessary, but that's not always true.

In case 1 above I think we could find a better way to do this. And I
don't think we should do case 2, though there may be special cases that
warrant it.

As possible alternate signalling methods I would like to propose the
following for consideration:

Exposing capabilities that a user is allowed to use. This has been
discussed before and there is general agreement that this is something
we would like in Nova. Capabilities will programatically inform users
that a new action has been added or an existing action can be performed
in more cases, like revert_resize. With that in place we can avoid the
ambiguous use of microversions to do that. In the meantime I would like
the team to consider not using microversions for this case. We have
enough of them being added that I think for now we could just wait for
the next microversion after a capability is added and document the new
capability there.

Secondly we could consider some indicator that exposes how new the code
in a deployment is. Rather than using microversions as a proxy to
indicate that a deployment has hit a certain point perhaps there could
be a header that indicates the date of the last commit in that code.
That's not an ideal way to implement it but hopefully it makes it clear
what I'm suggesting. Some marker that a user can use to determine that a
new behavior is to be expected, but not one that's more intended to
signal structural API changes.

Thoughts?

-Andrew