Re: [openstack-dev] [nova] The definition of 'Optional' parameter in API reference

[Matt Riedemann]

On 7/4/2017 7:13 PM, Takashi Natsume wrote:

On 2017/07/04 21:12, Alex Xu wrote:

2017-07-04 15:40 GMT+08:00 Ghanshyam Mann :


On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume
 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 


I noticed the same thing with hypervisor_links in the os-hypervisors 
API. The links are not shown if a limit is not in the request query 
parameters and there aren't more results than the default max limit 
(1000). In other words, you don't need links to another page if there is 
not another page to get.





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


Thanks for starting this thread. I've been struggling with this a bit 
too lately in some changes I'm working on, for example:


https://review.openstack.org/#/c/454322/

In there, instance_action_events are optional before 2.50, but required 
in >= 2.50. It gets doubly confusing because actually the 'events' in 
the response are required if you are an admin user before 2.50. So there 
are really three cases there:


1. Microversion < 2.50, admin user: 'events' are required
2. Microversion < 2.50, non-admin user: 'events' are optional
3. Microversion >= 2.50, admin or non-admin user: 'events' are required

I've tried to clarify with the description on each, and used the max/min 
versions for the behavior differences for when they are optional or not, 
but I can see where it's still a bit confusing.


--

Thanks,

Matt

__
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

Re: [openstack-dev] [nova] The definition of 'Optional' parameter in API reference

[Takashi Natsume]

On 2017/07/04 21:12, Alex Xu wrote:

2017-07-04 15:40 GMT+08:00 Ghanshyam Mann :


On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume
 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

Re: [openstack-dev] [nova] The definition of 'Optional' parameter in API reference

[Alex Xu]

2017-07-04 15:40 GMT+08:00 Ghanshyam Mann :

> On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume
>  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

Re: [openstack-dev] [nova] The definition of 'Optional' parameter in API reference

[Ghanshyam Mann]

On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume
 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

[openstack-dev] [nova] The definition of 'Optional' parameter in API reference

[Takashi Natsume]

Hi, all.

In Nova API reference, there is inconsistency in
whether to define parameters added in new microversion as 'optional' or not.

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



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


__
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