Open Stack

Agree with Andrew about Microversions may overused. I thought similar thing
before. The Microversions should be the version control of API 'core'
protocol.

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.

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.

So what I think we should design our API as a protocol, maybe that changed
the way of design our API.

But anyway, my thought just stop at this initial thought, I didn't get the
whole solution.

Thanks
Alex

2016-08-04 8:54 GMT+08:00 Andrew Laski <andrew at lascii.com>:

> 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
>
> __________________________________________________________________________
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160804/526471fe/attachment.html>