On Mon, Sep 22, 2014 at 4:29 AM, Kenichi Oomichi <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] > > 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? > (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 > 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