<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">2017-07-04 15:40 GMT+08:00 Ghanshyam Mann <span dir="ltr"><<a href="mailto:ghanshyammann@gmail.com" target="_blank">ghanshyammann@gmail.com</a>></span>:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-">On Mon, Jul 3, 2017 at 1:38 PM, Takashi Natsume<br>
<<a href="mailto:natsume.takashi@lab.ntt.co.jp">natsume.takashi@lab.ntt.co.jp</a><wbr>> wrote:<br>
> Hi, all.<br>
><br>
> In Nova API reference, there is inconsistency in<br>
> whether to define parameters added in new microversion as 'optional' or not.<br>
<br>
</span>Those should be defined based on how they are defined in respective<br>
microversion. If they are 'optional' in that microversion they should<br>
be mentioned as 'optional' and vice versa. Any parameter added in<br>
microversion is mentioned as 'New in version 2.xy' which shows the non<br>
availability of that parameter in earlier versions. Same case for<br>
removal of parameter also.<br>
<br>
But if any microversion change parameter from option param to required<br>
or vice versa then it is tricky but IMO documenting the latest<br>
behavior is right thing but with clear notes.<br>
For example, microversion 2.37,   where 'network' in request made as<br>
required from optional. In this cases, api-ref have the latest<br>
behavior of that param which is 'required' and a clear notes about<br>
till when it was optional and from when it is mandatory.<br>
<br>
In all cases, doc should reflect the latest behavior of param with<br>
notes(manual or auto generated with min_version & max_version)<br></blockquote><div><br></div><div>++</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<span class="gmail-"><br>
><br>
> In the case that the parameter is always included in the response after a<br>
> certain microversion,<br>
> some parameters(e.g. 'type' [1]) are defined as 'required', but some<br>
> parameters (e.g. 'project_id', 'user_id'[2])<br>
> are defined as 'optional'.<br>
><br>
> [1] List Keypairs in Keypairs (keypairs)<br>
> <a href="https://developer.openstack.org/api-ref/compute/?expanded=list-keypairs-detail#list-keypairs" rel="noreferrer" target="_blank">https://developer.openstack.<wbr>org/api-ref/compute/?expanded=<wbr>list-keypairs-detail#list-<wbr>keypairs</a></span></blockquote><div><br></div><div><font color="#333333" face="Open Sans, Helvetica, Arial, sans-serif"><span style="font-size:14px;background-color:rgb(249,249,249)">'keypairs_links' in the response should be the required parameter. Because it always show up after 2.35.</span></font><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-"><br>
><br>
> [2] List Server Groups in Server groups (os-server-groups)<br>
> <a href="https://developer.openstack.org/api-ref/compute/?expanded=list-server-groups-detail#list-server-groups" rel="noreferrer" target="_blank">https://developer.openstack.<wbr>org/api-ref/compute/?expanded=<wbr>list-server-groups-detail#<wbr>list-server-groups</a><br>
<br>
</span>'project_id', 'user_id' are introduced as 'required' from version 2.13<br>
[2] and should be added as 'required' in api doc also. i reported bug<br>
on this - <a href="https://bugs.launchpad.net/nova/+bug/1702238" rel="noreferrer" target="_blank">https://bugs.launchpad.net/<wbr>nova/+bug/1702238</a><br>
<span class="gmail-"><br>
<br>
><br>
> In the case that the parameter is always included in the response after a<br>
> certain microversion,<br>
> should it be defined as 'required' instead of 'optional'?<br>
><br>
> Regards,<br>
> Takashi Natsume<br>
> NTT Software Innovation Center<br>
> E-mail: <a href="mailto:natsume.takashi@lab.ntt.co.jp">natsume.takashi@lab.ntt.co.jp</a><br>
><br>
<br>
</span>..1 <a href="https://developer.openstack.org/api-ref/compute/?expanded=create-server-detail#create-server" rel="noreferrer" target="_blank">https://developer.openstack.<wbr>org/api-ref/compute/?expanded=<wbr>create-server-detail#create-<wbr>server</a><br>
..2 <a href="https://github.com/openstack/nova/blob/038619cce803c3522701886aa59c0c2750532b3a/nova/api/openstack/compute/server_groups.py#L104-L106" rel="noreferrer" target="_blank">https://github.com/openstack/<wbr>nova/blob/<wbr>038619cce803c3522701886aa59c0c<wbr>2750532b3a/nova/api/openstack/<wbr>compute/server_groups.py#L104-<wbr>L106</a><br>
<br>
-gmann<br>
<div class="gmail-HOEnZb"><div class="gmail-h5"><br>
><br>
> ______________________________<wbr>______________________________<wbr>______________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.<wbr>openstack.org?subject:<wbr>unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-dev</a><br>
<br>
______________________________<wbr>______________________________<wbr>______________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.<wbr>openstack.org?subject:<wbr>unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>