Open Stack

On Mon, Sep 22, 2014 at 4:29 AM, Kenichi Oomichi <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]
> > 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 at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140922/1f3c4e7b/attachment.html>