On 09/22/2014 05:29 AM, Kenichi Oomichi wrote:
-----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.
But finally, those implementations was considered too complex.

So I'm try to find out more simple implementation and solution for

I wrote down some ideas as blog post at:

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!

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.

Frankly, I believe the lack of perceived value in the v3 API was the reason backwards incompatibility was perceived as such a huge pain. v3 wasn't adding any functionality in the API that wasn't in v2, and v3 was bringing along with it much of the crap from the v2 API ... for example, API extensions and the ludicrous and needless complexity they add to the API.

If the v3 API had given users real additions in functionality, ease of use, and clarity, I think users would have embraced a new direction more -- especially if support for the v2 API was kept alongside the newer API for some period of time. But the v3 API didn't offer anything that application and tooling developers cared about. It offered some cleanups in return codes, some cleanups in resource naming and parameters, and not much else.

> 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

Sure, agreed.

(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
(1.3) Extension names should consist of hyphens and low chars.
   eg: OS-EXT-AZ:availability_zone -> 
       OS-EXT-STS:task_state -> os-extended-status:task_state
(1.4) Extension names should contain the prefix "os-" if the extension is not 
   eg: rxtx_factor -> os-flavor-rxtx:rxtx_factor
       os-flavor-access:is_public -> flavor-access:is_public (flavor-access 
extension became core)

Frankly, API extensions are a sore on the lip of OpenStack's smile.

They add needless complexity to the API and I believe a discoverable API with its resources micro-versioned with schema objects means that API extensions should just go the way of the Dodo.

(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"

-1. What is the point of the containing "server" attribute in the outer dict? Why have it at all?

Each resource in the REST API should have the same structure: all attributes should be top-level, and a special "_links" attribute should be used for the collection of named hyperlinks using the HAL format [1]. Simple, consistent, and discoverable. No need for the top-level "server" key in the outer dict. Frankly, that is a vestigial tail from the days of XML that we should saw off with a dull blade.

[1] http://stateless.co/hal_specification.html. An alternative might be the use of JSON-LD for link structuring. See https://www.mnot.net/blog/2011/11/25/linking_in_json for a good discussion of this topic.

(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 
   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 -> 

No extensions, please.

(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
(3.2) Return 204(No Content) if a resource deletion finishes before returning a 
   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 
   eg: "rescue a server" API: 200 ->202

++ on all above points.

I'd like to say finally that I think there should be an OpenStack API working group whose job it is to both pull together a set of OpenStack API practices as well as evaluate new REST APIs proposed in the OpenStack ecosystem to provide guidance to new projects or new subprojects wishing to add resources to an existing REST API.


Any comments are welcome.

Ken'ichi Ohmichi

OpenStack-dev mailing list

OpenStack-dev mailing list

Reply via email to