<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Sep 22, 2014 at 4:29 AM, Kenichi Oomichi <span dir="ltr"><<a href="mailto:oomichi@mxs.nes.nec.co.jp" target="_blank">oomichi@mxs.nes.nec.co.jp</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi Alex,<br>
<br>
Thank you for doing this.<br>
<span class=""><br>
> -----Original Message-----<br>
> From: Alex Xu [mailto:<a href="mailto:xuhj@linux.vnet.ibm.com">xuhj@linux.vnet.ibm.com</a>]<br>
> Sent: Friday, September 19, 2014 3:40 PM<br>
> To: OpenStack Development Mailing List<br>
> Subject: [openstack-dev] [Nova] Some ideas for micro-version implementation<br>
><br>
> Close to Kilo, it is time to think about what's next for nova API. In<br>
> Kilo, we<br>
> will continue develop the important feature micro-version.<br>
><br>
> In previous v2 on v3 propose, it's include some implementations can be<br>
> used for micro-version.<br>
> (<a href="https://review.openstack.org/#/c/84695/19/specs/juno/v2-on-v3-api.rst" target="_blank">https://review.openstack.org/#/c/84695/19/specs/juno/v2-on-v3-api.rst</a>)<br>
> But finally, those implementations was considered too complex.<br>
><br>
> So I'm try to find out more simple implementation and solution for<br>
> micro-version.<br>
><br>
> I wrote down some ideas as blog post at:<br>
> <a href="http://soulxu.github.io/blog/2014/09/12/one-option-for-nova-api/" target="_blank">http://soulxu.github.io/blog/2014/09/12/one-option-for-nova-api/</a><br>
><br>
> And for those ideas also already done some POC, you can find out in the<br>
> blog post.<br>
><br>
> As discussion in the Nova API meeting, we want to bring it up to<br>
> mail-list to<br>
> discussion. Hope we can get more idea and option from all developers.<br>
><br>
> We will appreciate for any comment and suggestion!<br></span></blockquote><div><br></div><div>I would greatly appreciate this style guide to be finalized for documentation purposes as well. Thanks for starting this write-up. I'd be happy to write it up on a wiki page while we get agreement, would that be helpful?<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">
<br>
</span>Before discussing how to implement, I'd like to consider what we should<br>
implement. IIUC, the purpose of v3 API is to make consistent API with the<br>
backwards incompatible changes. Through huge discussion in Juno cycle, we<br>
knew that backwards incompatible changes of REST API would be huge pain<br>
against clients and we should avoid such changes as possible. If new APIs<br>
which are consistent in Nova API only are inconsistent for whole OpenStack<br>
projects, maybe we need to change them again for whole OpenStack consistency.<br>
<br>
For avoiding such situation, I think we need to define what is consistent<br>
REST API across projects. According to Alex's blog, The topics might be<br>
<br>
- Input/Output attribute names<br>
- Resource names<br>
- Status code<br>
<br>
The following are hints for making consistent APIs from Nova v3 API experience,<br>
I'd like to know whether they are the best for API consistency.<br>
<br>
(1) Input/Output attribute names<br>
(1.1) These names should be snake_case.<br>
eg: imageRef -> image_ref, flavorRef -> flavor_ref, hostId -> host_id<br>
(1.2) These names should contain extension names if they are provided in case of some extension loading.<br>
eg: security_groups -> os-security-groups:security_groups<br>
config_drive -> os-config-drive:config_drive<br></blockquote><div><br></div><div>Do you mean that the os- prefix should be dropped? Or that it should be maintained and added as needed?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
(1.3) Extension names should consist of hyphens and low chars.<br>
eg: OS-EXT-AZ:availability_zone -> os-extended-availability-zone:availability_zone<br>
OS-EXT-STS:task_state -> os-extended-status:task_state<br></blockquote><div><br></div><div>Yes, I don't like the shoutyness of the ALL CAPS.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
(1.4) Extension names should contain the prefix "os-" if the extension is not core.<br>
eg: rxtx_factor -> os-flavor-rxtx:rxtx_factor<br>
os-flavor-access:is_public -> flavor-access:is_public (flavor-access extension became core)<br></blockquote><div><br></div><div>Do we have a list of "core" yet?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
(1.5) The length of the first attribute depth should be one.<br>
eg: "create a server" API with scheduler hints<br>
-- v2 API input attribute sample ---------------------------------------<br>
{<br>
"server": {<br>
"imageRef": "e5468cc9-3e91-4449-8c4f-e4203c71e365",<br>
[..]<br>
},<br>
"OS-SCH-HNT:scheduler_hints": {<br>
"same_host": "5a3dec46-a6e1-4c4d-93c0-8543f5ffe196"<br>
}<br>
}<br>
-- v3 API input attribute sample ---------------------------------------<br>
{<br>
"server": {<br>
"image_ref": "e5468cc9-3e91-4449-8c4f-e4203c71e365",<br>
[..]<br>
"os-scheduler-hints:scheduler_hints": {<br>
"same_host": "5a3dec46-a6e1-4c4d-93c0-8543f5ffe196"<br>
}<br>
}<br>
}<br>
<br>
(2) Resource names<br>
(2.1) Resource names should consist of hyphens and low chars.<br>
eg: /os-instance_usage_audit_log -> /os-instance-usage-audit-log<br>
(2.2) Resource names should contain the prefix "os-" if the extension is not core.<br>
eg: /servers/diagnostics -> /servers/os-server-diagnostics<br>
/os-flavor-access -> /flavor-access (flavor-access extension became core)<br>
(2.3) Action names should be snake_case.<br>
eg: os-getConsoleOutput -> get_console_output<br>
addTenantAccess -> add_tenant_access, removeTenantAccess -> remove_tenant_access<br>
<br></blockquote><div><br></div><div>Yes to all of these.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
(3) Status code<br>
(3.1) Return 201(Created) if a resource creation/updating finishes before returning a response.<br>
eg: "create a keypair" API: 200 -> 201<br>
"create an agent" API: 200 -> 201<br>
"create an aggregate" API: 200 -> 201<br></blockquote><div><br></div><div>Do you mean a 200 becomes a 201? That's a huge doc impact and SDK impact, is it worthwhile? If we do this change, the sooner the better, right?</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
(3.2) Return 204(No Content) if a resource deletion finishes before returning a response.<br>
eg: "delete a keypair" API: 200 -> 204<br>
"delete an agent" API: 200 -> 204<br>
"delete an aggregate" API: 200 -> 204<br>
(3.3) Return 202(Accepted) if a request doesn't finish yet before returning a response.<br>
eg: "rescue a server" API: 200 ->202<br>
<br></blockquote><div><br></div><div>Same here, sooner the better if these are better response codes.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Any comments are welcome.<br>
<br></blockquote><div><br></div><div>The TC had an action item a while back (a few months) to start an API style guide. This seems like a good start. Once the questions are discussed I'll get a draft going on the wiki. </div><div><br></div><div>Thanks,</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Thanks<br>
Ken'ichi Ohmichi<br>
<div class=""><div class="h5"><br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>