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 <and...@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-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev