Open Stack

On 2017/07/04 21:12, Alex Xu wrote:
> 2017-07-04 15:40 GMT+08:00 Ghanshyam Mann <ghanshyammann at gmail.com>:
>
>> On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume
>> <natsume.takashi at 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.takashi at lab.ntt.co.jp