? 2014?09?22? 22:47, Anne Gentle ??:
On Mon, Sep 22, 2014 at 4:29 AM, Kenichi Oomichi <oomi...@mxs.nes.nec.co.jp <mailto:oomi...@mxs.nes.nec.co.jp>> wrote:Hi Alex, Thank you for doing this. > -----Original Message----- > From: Alex Xu [mailto:x...@linux.vnet.ibm.com <mailto:x...@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_driveDo 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 -> 201Do 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@lists.openstack.org <mailto:OpenStack-dev@lists.openstack.org> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-- Thanks, Eli (Li Yong) Qiao
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
