<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
<link href="chrome://translator/skin/floatingPanel.css"
type="text/css" rel="stylesheet">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<br>
<div class="moz-cite-prefix">于 2014年09月22日 22:47, Anne Gentle 写道:<br>
</div>
<blockquote
cite="mid:CAD0KtVGvXNGK7V_Pe+161O1ptJdcTqGD5Nzj+TMXptojS9p1Yw@mail.gmail.com"
type="cite">
<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
moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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>
</div>
</div>
</div>
</blockquote>
<blockquote
cite="mid:CAD0KtVGvXNGK7V_Pe+161O1ptJdcTqGD5Nzj+TMXptojS9p1Yw@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<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>
</div>
</div>
</div>
</blockquote>
I don't think all 200 becomes 201<br>
200 mean accepted and processed.<br>
201 mean accepted and resources have been created.<br>
for some apis, 201 is much reasonable then 200.<br>
<br>
thanks Eli.<br>
<blockquote
cite="mid:CAD0KtVGvXNGK7V_Pe+161O1ptJdcTqGD5Nzj+TMXptojS9p1Yw@mail.gmail.com"
type="cite">
<div dir="ltr">
<div class="gmail_extra">
<div class="gmail_quote">
<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 moz-do-not-send="true"
href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a moz-do-not-send="true"
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>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Thanks,
Eli (Li Yong) Qiao</pre>
<div style="bottom: auto; left: 10px; right: auto; top: 298px;"
class="translator-theme-default" id="translator-floating-panel">
<div title="点击翻译" id="translator-floating-panel-button"></div>
</div>
</body>
</html>