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 > > [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/038619cce803c3522701886aa59c0c2750532b3a/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
