Open Stack

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!

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

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

Any comments are welcome.

Thanks
Ken'ichi Ohmichi