2017-07-04 15:40 GMT+08:00 Ghanshyam Mann <ghanshyamm...@gmail.com>: > On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume > <natsume.taka...@lab.ntt.co.jp> wrote: > > Hi, all. > > > > In Nova API reference, there is inconsistency in > > whether to define parameters added in new microversion as 'optional' or > not. > > Those should be defined based on how they are defined in respective > microversion. If they are 'optional' in that microversion they should > be mentioned as 'optional' and vice versa. Any parameter added in > microversion is mentioned as 'New in version 2.xy' which shows the non > availability of that parameter in earlier versions. Same case for > removal of parameter also. > > But if any microversion change parameter from option param to required > or vice versa then it is tricky but IMO documenting the latest > behavior is right thing but with clear notes. > For example, microversion 2.37, where 'network' in request made as > required from optional. In this cases, api-ref have the latest > behavior of that param which is 'required' and a clear notes about > till when it was optional and from when it is mandatory. > > In all cases, doc should reflect the latest behavior of param with > notes(manual or auto generated with min_version & max_version) >
++ > > > > > In the case that the parameter is always included in the response after a > > certain microversion, > > some parameters(e.g. 'type' [1]) are defined as 'required', but some > > parameters (e.g. 'project_id', 'user_id'[2]) > > are defined as 'optional'. > > > > [1] List Keypairs in Keypairs (keypairs) > > https://developer.openstack.org/api-ref/compute/?expanded= > list-keypairs-detail#list-keypairs 'keypairs_links' in the response should be the required parameter. Because it always show up after 2.35. > > > > > [2] List Server Groups in Server groups (os-server-groups) > > https://developer.openstack.org/api-ref/compute/?expanded= > list-server-groups-detail#list-server-groups > > 'project_id', 'user_id' are introduced as 'required' from version 2.13 > [2] and should be added as 'required' in api doc also. i reported bug > on this - https://bugs.launchpad.net/nova/+bug/1702238 > > > > > > In the case that the parameter is always included in the response after a > > certain microversion, > > should it be defined as 'required' instead of 'optional'? > > > > Regards, > > Takashi Natsume > > NTT Software Innovation Center > > E-mail: natsume.taka...@lab.ntt.co.jp > > > > ..1 https://developer.openstack.org/api-ref/compute/?expanded= > create-server-detail#create-server > ..2 https://github.com/openstack/nova/blob/038619cce803c3522701886aa59c0c > 2750532b3a/nova/api/openstack/compute/server_groups.py#L104-L106 > > -gmann > > > > > ____________________________________________________________ > ______________ > > 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
