[openstack-dev] [Nova] Some ideas for micro-version implementation

Eli Qiao taget at linux.vnet.ibm.com
Tue Sep 23 04:05:14 UTC 2014


? 2014?09?22? 22:47, Anne Gentle ??:
>
>
> On Mon, Sep 22, 2014 at 4:29 AM, Kenichi Oomichi 
> <oomichi at mxs.nes.nec.co.jp <mailto:oomichi at mxs.nes.nec.co.jp>> wrote:
>
>     Hi Alex,
>
>     Thank you for doing this.
>
>     > -----Original Message-----
>     > From: Alex Xu [mailto:xuhj at linux.vnet.ibm.com
>     <mailto:xuhj at linux.vnet.ibm.com>]
>     > Sent: Friday, September 19, 2014 3:40 PM
>     > To: OpenStack Development Mailing List
>     > Subject: [openstack-dev] [Nova] Some ideas for micro-version
>     implementation
>     >
>     > Close to Kilo, it is time to think about what's next for nova
>     API. In
>     > Kilo, we
>     > will continue develop the important feature micro-version.
>     >
>     > In previous v2 on v3 propose, it's include some implementations
>     can be
>     > used for micro-version.
>     >
>     (https://review.openstack.org/#/c/84695/19/specs/juno/v2-on-v3-api.rst)
>     > But finally, those implementations was considered too complex.
>     >
>     > So I'm try to find out more simple implementation and solution for
>     > micro-version.
>     >
>     > I wrote down some ideas as blog post at:
>     > http://soulxu.github.io/blog/2014/09/12/one-option-for-nova-api/
>     >
>     > And for those ideas also already done some POC, you can find out
>     in the
>     > blog post.
>     >
>     > As discussion in the Nova API meeting, we want to bring it up to
>     > mail-list to
>     > discussion. Hope we can get more idea and option from all
>     developers.
>     >
>     > We will appreciate for any comment and suggestion!
>
>
> 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?
>
>
>     Before discussing how to implement, I'd like to consider what we
>     should
>     implement. IIUC, the purpose of v3 API is to make consistent API
>     with the
>     backwards incompatible changes. Through huge discussion in Juno
>     cycle, we
>     knew that backwards incompatible changes of REST API would be huge
>     pain
>     against clients and we should avoid such changes as possible. If
>     new APIs
>     which are consistent in Nova API only are inconsistent for whole
>     OpenStack
>     projects, maybe we need to change them again for whole OpenStack
>     consistency.
>
>     For avoiding such situation, I think we need to define what is
>     consistent
>     REST API across projects. According to Alex's blog, The topics
>     might be
>
>      - Input/Output attribute names
>      - Resource names
>      - Status code
>
>     The following are hints for making consistent APIs from Nova v3
>     API experience,
>     I'd like to know whether they are the best for API consistency.
>
>     (1) Input/Output attribute names
>     (1.1) These names should be snake_case.
>       eg: imageRef -> image_ref, flavorRef -> flavor_ref, hostId ->
>     host_id
>     (1.2) These names should contain extension names if they are
>     provided in case of some extension loading.
>       eg: security_groups -> os-security-groups:security_groups
>           config_drive -> os-config-drive:config_drive
>
>
> Do you mean that the os- prefix should be dropped? Or that it should 
> be maintained and added as needed?
>
>     (1.3) Extension names should consist of hyphens and low chars.
>       eg: OS-EXT-AZ:availability_zone ->
>     os-extended-availability-zone:availability_zone
>           OS-EXT-STS:task_state -> os-extended-status:task_state
>
>
> Yes, I don't like the shoutyness of the ALL CAPS.
>
>     (1.4) Extension names should contain the prefix "os-" if the
>     extension is not core.
>       eg: rxtx_factor -> os-flavor-rxtx:rxtx_factor
>           os-flavor-access:is_public -> flavor-access:is_public
>     (flavor-access extension became core)
>
>
> Do we have a list of "core" yet?
>
>     (1.5) The length of the first attribute depth should be one.
>       eg: "create a server" API with scheduler hints
>         -- v2 API input attribute sample
>     ---------------------------------------
>           {
>               "server": {
>                   "imageRef": "e5468cc9-3e91-4449-8c4f-e4203c71e365",
>                   [..]
>               },
>               "OS-SCH-HNT:scheduler_hints": {
>                   "same_host": "5a3dec46-a6e1-4c4d-93c0-8543f5ffe196"
>               }
>           }
>         -- v3 API input attribute sample
>     ---------------------------------------
>           {
>               "server": {
>                   "image_ref": "e5468cc9-3e91-4449-8c4f-e4203c71e365",
>                   [..]
>                   "os-scheduler-hints:scheduler_hints": {
>                       "same_host": "5a3dec46-a6e1-4c4d-93c0-8543f5ffe196"
>                   }
>               }
>           }
>
>     (2) Resource names
>     (2.1) Resource names should consist of hyphens and low chars.
>       eg: /os-instance_usage_audit_log -> /os-instance-usage-audit-log
>     (2.2) Resource names should contain the prefix "os-" if the
>     extension is not core.
>       eg: /servers/diagnostics -> /servers/os-server-diagnostics
>           /os-flavor-access -> /flavor-access (flavor-access extension
>     became core)
>     (2.3) Action names should be snake_case.
>       eg: os-getConsoleOutput -> get_console_output
>           addTenantAccess -> add_tenant_access, removeTenantAccess ->
>     remove_tenant_access
>
>
> Yes to all of these.
>
>     (3) Status code
>     (3.1) Return 201(Created) if a resource creation/updating finishes
>     before returning a response.
>       eg: "create a keypair" API: 200 -> 201
>           "create an agent" API: 200 -> 201
>           "create an aggregate" API: 200 -> 201
>
>
> 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?
I don't think all 200 becomes 201
200 mean accepted and processed.
201 mean accepted and resources have been created.
for some apis, 201 is much reasonable then 200.

thanks Eli.
>
>     (3.2) Return 204(No Content) if a resource deletion finishes
>     before returning a response.
>       eg: "delete a keypair" API: 200 -> 204
>           "delete an agent" API: 200 -> 204
>           "delete an aggregate" API: 200 -> 204
>     (3.3) Return 202(Accepted) if a request doesn't finish yet before
>     returning a response.
>       eg: "rescue a server" API: 200 ->202
>
>
> Same here, sooner the better if these are better response codes.
>
>     Any comments are welcome.
>
>
> 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.
>
> Thanks,
> Anne
>
>     Thanks
>     Ken'ichi Ohmichi
>
>     _______________________________________________
>     OpenStack-dev mailing list
>     OpenStack-dev at lists.openstack.org
>     <mailto:OpenStack-dev at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-- 
Thanks,
Eli (Li Yong) Qiao

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140923/0bcb0926/attachment.html>


More information about the OpenStack-dev mailing list