On 2017/07/04 21:12, Alex Xu wrote:
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:
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)
++
Thank you for your replies and the fix in
https://review.openstack.org/#/c/480162/ .
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.
The 'keypairs_links' is an optional parameter.
When the 'get_links' method of the view builder for keypairs operations
returns an empty list, the 'keypairs_links' does not appear
in the response.
https://github.com/openstack/nova/blob/32e613b9cd499847b7a7dc49d43020523b96c1d1/nova/api/openstack/compute/keypairs.py#L286-L288
Regards,
Takashi Natsume
NTT Software Innovation Center
E-mail: natsume.taka...@lab.ntt.co.jp
__________________________________________________________________________
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
