<div dir="ltr">Agree with Andrew about Microversions may overused. I thought similar thing before. The Microversions should be the version control of API 'core' protocol.<div><br></div><div>So I can say the protocol of send an action to server is: 'POST /servers/{uuid}/action'. We won't bump microversion for any new action or action removed. We only bump Microversion when the protocol changed, like the new way send action: 'POST /servers/{uuid}/{action_name}'. Whether the current cloud support specific action or not, that is done by capability discover API. At this point, I think what I thought is same with Andrew (If I understand this email correctly...). But I stuck at the point, I use Microversion define the protocol, I use the capabilities API for action discovery. What I should used for version the body of action? That sounds a nest protocol. Another version for the body of action? Ooh, that is too complex for user, too much layer control.<div><br></div><div>Another example is scheduler_hints, we discuss whether we should write each hint into the schema. So we should say the protocol is: You can input the scheduler_hint into the field 'scheduler_hints' of server boot body. Each hint is a key and a value in a dict. What scheduler_hint supported in the cloud, the kind of value is accepted by specific scheduler_hint, that should be controlled by another thing.</div></div><div><br></div><div>So what I think we should design our API as a protocol, maybe that changed the way of design our API.</div><div><br></div><div>But anyway, my thought just stop at this initial thought, I didn't get the whole solution.</div><div><br></div><div>Thanks</div><div>Alex</div></div><div class="gmail_extra"><br><div class="gmail_quote">2016-08-04 8:54 GMT+08:00 Andrew Laski <span dir="ltr"><<a href="mailto:andrew@lascii.com" target="_blank">andrew@lascii.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I've brought some of these thoughts up a few times in conversations<br>
where the Nova team is trying to decide if a particular change warrants<br>
a microversion. I'm sure I've annoyed some people by this point because<br>
it wasn't germane to those discussions. So I'll lay this out in it's own<br>
thread.<br>
<br>
I am a fan of microversions. I think they work wonderfully to express<br>
when a resource representation changes, or when different data is<br>
required in a request. This allows clients to make the same request<br>
across multiple clouds and expect the exact same response format,<br>
assuming those clouds support that particular microversion. I also think<br>
they work well to express that a new resource is available. However I do<br>
think think they have some shortcomings in expressing that a resource<br>
has been removed. But in short I think microversions work great for<br>
expressing that there have been changes to the structure and format of<br>
the API.<br>
<br>
I think microversions are being overused as a signal for other types of<br>
changes in the API because they are the only tool we have available. The<br>
most recent example is a proposal to allow the revert_resize API call to<br>
work when a resizing instance ends up in an error state. I consider<br>
microversions to be problematic for changes like that because we end up<br>
in one of two situations:<br>
<br>
1. The microversion is a signal that the API now supports this action,<br>
but users can perform the action at any microversion. What this really<br>
indicates is that the deployment being queried has upgraded to a certain<br>
point and has a new capability. The structure and format of the API have<br>
not changed so an API microversion is the wrong tool here. And the<br>
expected use of a microversion, in my opinion, is to demarcate that the<br>
API is now different at this particular point.<br>
<br>
2. The microversion is a signal that the API now supports this action,<br>
and users are restricted to using it only on or after that microversion.<br>
In many cases this is an artificial constraint placed just to satisfy<br>
the expectation that the API does not change before the microversion.<br>
But the reality is that if the API change was exposed to every<br>
microversion it does not affect the ability I lauded above of a client<br>
being able to send the same request and receive the same response from<br>
disparate clouds. In other words exposing the new action for all<br>
microversions does not affect the interoperability story of Nova which<br>
is the real use case for microversions. I do recognize that the<br>
situation may be more nuanced and constraining the action to specific<br>
microversions may be necessary, but that's not always true.<br>
<br>
In case 1 above I think we could find a better way to do this. And I<br>
don't think we should do case 2, though there may be special cases that<br>
warrant it.<br>
<br>
As possible alternate signalling methods I would like to propose the<br>
following for consideration:<br>
<br>
Exposing capabilities that a user is allowed to use. This has been<br>
discussed before and there is general agreement that this is something<br>
we would like in Nova. Capabilities will programatically inform users<br>
that a new action has been added or an existing action can be performed<br>
in more cases, like revert_resize. With that in place we can avoid the<br>
ambiguous use of microversions to do that. In the meantime I would like<br>
the team to consider not using microversions for this case. We have<br>
enough of them being added that I think for now we could just wait for<br>
the next microversion after a capability is added and document the new<br>
capability there.<br>
<br>
Secondly we could consider some indicator that exposes how new the code<br>
in a deployment is. Rather than using microversions as a proxy to<br>
indicate that a deployment has hit a certain point perhaps there could<br>
be a header that indicates the date of the last commit in that code.<br>
That's not an ideal way to implement it but hopefully it makes it clear<br>
what I'm suggesting. Some marker that a user can use to determine that a<br>
new behavior is to be expected, but not one that's more intended to<br>
signal structural API changes.<br>
<br>
Thoughts?<br>
<br>
-Andrew<br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div><br></div>