FWIW, we enumerated the use-cases and expected behavior for all combinations of server [pre versions, older version, newer version] and client [pre versions, older version, newer version, user-specified version], in this "informational" spec:
http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#proposed-change Not all of that is implemented yet within our client, but the auto-negotiation of version is done. While our clients probably don't share any code, maybe something here can help: http://git.openstack.org/cgit/openstack/python-ironicclient/tree/ironicclient/common/http.py#n72 -Deva On Mon, Apr 27, 2015 at 2:49 AM, John Garbutt <j...@johngarbutt.com> wrote: > I see these changes as really important. > > We need to establish good patterns other SDKs can copy. > > On 24 April 2015 at 12:05, Alex Xu <sou...@gmail.com> wrote: >> 2015-04-24 18:15 GMT+08:00 Andrey Kurilin <akuri...@mirantis.com>: >>> >When user execute cmd without --os-compute-version. The nova client >>> > should discover the nova server >supported version. Then cmd choice the >>> > latest version supported both by client and server. >>> >>> In that case, why X-Compute-API-Version can accept "latest" value? Also, >>> such discovery will require extra request to API side for every client call. >>> >> >> I think it is convenient for some case. like give user more easy to try nova >> api by some code access the nova api directly. Yes, it need one more extra >> request. But if without discover, we can't ensure the client support server. >> Maybe client too old for server even didn't support the server's min >> version. For better user experience, I think it worth to discover the >> version. And we will call keystone each nova client cli call, so it is >> acceptable. > > We might need to extend the API to make this easier, but I think we > need to come up with a simple and efficient pattern here. > > > Case 1: > Existing python-novaclient calls, now going to v2.1 API > > We can look for the transitional entry of computev21, as mentioned > above, but it seems fair to assume v2.1 and v2.0 are accessed from the > same service catalog entry of "compute", by default (eventually). > > Lets be optimistic about what the cloud supports, and request "latest" > version from v2.1. > > If its a v2.0 only API endpoint, we will not get back a version header > with the response, we could error out if the user requested v2.x > min_version via the CLI parameters. > > In most cases, we get the latest return values, and all is well. > > > Case 2: > User wants some info they know was added to the response in a specific > microversion > > We can request "latest" and error out if we don't get a new enough > version to meet the user's min requirement. > > > Case 3: > Adding support for a new request added in a microversion > > We could just send "latest" and assume the new functionality, then > raise an error when you get bad request (or similar), and check the > version header to see if that was the cause of the problem, so we can > say why it failed. > > If its supported, everything just works. > > If the user requests a specific version before it was supported, we > should error out as not supported, I guess? > > In a way it would be cleaner if we had a way for the client to say > "latest but requires 2.3", so you get a bad version request if your > minimum requirement is not respected, so its much clearer than > miss-interpreting random errors that you might generate. But I guess > its not totally required here. > > > Would all that work? It should avoid an extra API call to discover the > specific version we have available. > >>> >'--os-compute-version=None' can be supported, that means will return the >>> > min version of server supported. >>> >>> From my point of view '--os-compute-version=None' is equal to not >>> specified value. Maybe, it would be better to accept value "min" for >>> os-compute-version option. >> >> I think '--os-compute-version=None' means not specified version request >> header when send api request to server. The server behavior is if there >> isn't value specified, the min version will be used. > > --os-compte-version=v2 means no version specified I guess? > > Can we go back to the use cases here please? > What do the users need here and why? > > >>> >3. if the microversion non-supported, but user call cmd with >>> > --os-compute-version, this should return failed. >>> >>> Imo, it should be implemented on API side(return BadRequest when >>> X-Compute-API-Version header is presented in V2) > > V2 is already deployed now, and doesn't do that. > > No matter what happens we need to fix that. >> >> Emm.... I'm not sure. Because GET '/v2/' already can be used to discover >> microversion support or not. Sounds like add another way to support >> discover? And v2 api didn't return fault with some extra header, that sounds >> like behavior and back-incompatible change. > > -1 > > We should not use the URL to detect the version. > We have other ways to do that for a good reason. > > Thanks, > John > > > >>> On Fri, Apr 24, 2015 at 12:42 PM, Alex Xu <sou...@gmail.com> wrote: >>>> >>>> >>>> >>>> 2015-04-24 17:24 GMT+08:00 Andrey Kurilin <akuri...@mirantis.com>: >>>>> >>>>> Thank you for suggestions! I'll try modify patches as soon as possible. >>>> >>>> >>>> np, it's better waiting for more comment before you begin to update the >>>> code first. avoid you need rework again I think :) >>>> >>>>> >>>>> >>>>> On Fri, Apr 24, 2015 at 6:56 AM, Alex Xu <sou...@gmail.com> wrote: >>>>>> >>>>>> Thanks Andrey for hard work on the microverison client support. >>>>>> >>>>>> Wrote down some my thought: >>>>>> >>>>>> I also agreed we will have only one endpoint 'compute'. Hope we can >>>>>> switch v2.1 export as '/v2' in the api-paste.conf as default very soon~ >>>>>> >>>>>> let's say what expected after we only have v2.1 in the world first: >>>>>> >>>>>> There are two cases for use nova client. >>>>>> 1. user use nova client command line. I think command line should >>>>>> support version discover. Provide most convenient way let the user try >>>>>> nova. >>>>>> 2. user use nova client as library. user should call the client code to >>>>>> discover the version and decided what version he want to use by himself. >>>>>> >>>>>> For the command line, the behavior can be: >>>>>> >>>>>> When user execute cmd without --os-compute-version. The nova client >>>>>> should discover the nova server supported version. Then cmd choice the >>>>>> latest version supported both by client and server. This is good for us >>>>>> to >>>>>> introduce the new feature to the user. >>>>>> >>>>>> Also user can specified a version he want to by --os-compute-version. >>>>>> >>>>>> '--os-compute-version=None' can be supported, that means will return >>>>>> the min version of server supported. >>>>>> >>>>>> The supported version can be discovered by version API (Thanks to >>>>>> Ken'ichi fix this): >>>>>> GET '/' >>>>>> >>>>>> https://github.com/openstack/nova/blob/master/doc/api_samples/versions/versions-get-resp.json#L25 >>>>>> >>>>>> But reality is the v2 and v2.1 will existed at same time. >>>>>> >>>>>> So the v2 or v2.1 code both can run under the endpoint 'compute' with >>>>>> url '/v2'. It depend on the admin's deployment. >>>>>> >>>>>> So I think the cmd also can discover whether the api supported >>>>>> microversion under the 'compute' endpoint. >>>>>> >>>>>> This can be discovered by version api also. >>>>>> >>>>>> GET '/v2/' will return the endpoint version info. Then we can check the >>>>>> version and min_version properties to know whether the api support >>>>>> microversion or not. >>>>>> >>>>>> The behavior can be: >>>>>> 1. If the microversion supported, the cmd behavior is same as the >>>>>> description at the top of this mail >>>>>> 2. If the microversion non-supported, user call cmd without >>>>>> --os-compute-version, we use the min version. >>>>>> 3. if the microversion non-supported, but user call cmd with >>>>>> --os-compute-version, this should return failed. >>>>>> >>>>>> Hope those thoughts are helpful. >>>>>> >>>>>> Looks like this need some change in current patchset also :( I know >>>>>> Andrey already pay lot of on this. But if we like this way, I also can >>>>>> give >>>>>> some help on the coding :) >>>>>> >>>>>> Thanks >>>>>> Alex >>>>>> >>>>>> >>>>>> 2015-04-10 19:30 GMT+08:00 Andrey Kurilin <akuri...@mirantis.com>: >>>>>>> >>>>>>> Hi all! >>>>>>> I working on implementation of support microversions in novaclient. >>>>>>> Patches are ready for review, but there is one opened question: what we >>>>>>> should do with v2.1 endpoint(computev21 service type)? >>>>>>> >>>>>>> "compute" is a default value of service type and keystone returns v2 >>>>>>> api endpoint for it(at least in devstack), so version header will be >>>>>>> ignored >>>>>>> on API side. >>>>>>> >>>>>>> On the one hand, each deployment can have it's own configuration of >>>>>>> service catalog and endpoints, so default value of service type should >>>>>>> be >>>>>>> strict and support as much deployments as we can. On the other hand, >>>>>>> dependency of service type for microversion feature is not good and >>>>>>> end-users should not take care about choice of correct service type when >>>>>>> they want to execute simple command. >>>>>>> >>>>>>> Possible solutions: >>>>>>> >>>>>>> leave everything as is: use "--service-type computev21" for each >>>>>>> microversioned command >>>>>>> move default value of service type to environment variables(default >>>>>>> value is hardcoded in novaclient code now) >>>>>>> add additional option --compute-api-type. Proposed etherpad by >>>>>>> Christopher Yeoh >>>>>>> https://etherpad.openstack.org/p/novaclient_microversions_design . >>>>>>> Implementation is already finished - >>>>>>> https://review.openstack.org/#/c/167577/ . This proposal still requires >>>>>>> addition cli option, but compute-api-type looks more user-friendly >>>>>>> >>>>>>> >>>>>>> Current implementation uses "compute" as default value for service >>>>>>> type. Patches are pass all gates, except stable branches and ready for >>>>>>> review: >>>>>>> >>>>>>> https://review.openstack.org/#/c/169378/ - deprecate v1.1 and remove >>>>>>> references to v3 in code >>>>>>> https://review.openstack.org/#/c/152569/ - Implements 'microversions' >>>>>>> api type - Part 1 (usage of >>>>>>> nova.api.openstack.api_version_request:APIVersionRequest class with >>>>>>> https://review.openstack.org/#/c/169292/ ) >>>>>>> https://review.openstack.org/#/c/167408/ - Implements 'microversions' >>>>>>> api type - Part 2 (adds new decorators and substitution mechanism using >>>>>>> nova.api.openstack.versioned_method ) >>>>>>> https://review.openstack.org/#/c/136458/ - Implementation of 2.2 >>>>>>> microversion >>>>>>> >>>>>>> >>>>>>> -- >>>>>>> Best regards, >>>>>>> Andrey Kurilin. >>>>>>> >>>>>>> >>>>>>> __________________________________________________________________________ >>>>>>> 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 >>>>>> >>>>> >>>>> >>>>> >>>>> -- >>>>> Best regards, >>>>> Andrey Kurilin. >>>>> >>>>> >>>>> __________________________________________________________________________ >>>>> 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 >>>> >>> >>> >>> >>> -- >>> Best regards, >>> Andrey Kurilin. >>> >>> __________________________________________________________________________ >>> 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 >> > > __________________________________________________________________________ > 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
