Open Stack

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:
> > 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.takashi at 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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170704/3de834b9/attachment.html>