On Mon, 22 Sep 2014 09:29:26 +0000
Kenichi Oomichi <oomi...@mxs.nes.nec.co.jp> wrote:
> 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.

So I think there's three different aspects to microversions which we
can consider quit separately:

- The format of the client header and what the version number means.
  Eg is the version number of the format X.Y.Z, what do we increment
  when we make a bug fix, what do we increment when we make a backwards
  compatible change and what do we increment when we make backwards
  incompatible change.

  Also how does a client request experimental APIs (I believe we have
  consensus that we really need this to avoid backwards incompatible
  changes as much as possible as it allows more testing before
  guaranteeing backwards compatibility)

  I believe that we can consider this part separately from the next two

- The implementation on the nova api side. Eg how do we cleanly handle
  supporting multiple versions of the api based on the client header
  (or lack of it which will indicate v2 compatibility. I'll respond
  directly on Alex's original post

- What we are going to use the microversions API feature to do. I think
  they fall under a few broad categories: 

  - Backwards compatible changes. We desperately need a mechanism that
    allows us to make backwards compatible changes (eg add another
    parameter to a response) without having to add another dummy

  - Significant backwards incompatible changes. The Tasks API and server
    diagnostics API are probably the best examples of this. 

  - V3 like backwards incompatible changes (consistency fixes).

I think getting consensus over backwards compatible changes will be
straightforward. However given the previous v2/v3 discussions I don't
think we will be able to get consensus over doing all or most of the
consistency type fixes even using microversions in the short term.
Because with microversions you get all the changes applied before the
version that you choose. So from a client application point of view its
just as much work as V2 to V3 API transition.

I don't think that means we need to put all of these consistency
changes off forever though. We need to make backwards incompatible
changes in order to implement the Tasks API  and new server
diagnostics api the way we want to. The Tasks API will eventually cover
quite a few interfaces and while say breaking backwards compatibility
with the create server api, we can also fix consistency issues in that
api at the same time. Clients will need to make changes to their app
anyway if they want to take advantage of the new features (or they can
just continue to use the old non-tasks enabled API).

So as we slowly make backwards incompatible changes to the API for
other reasons we can also fix up other issues. Other consistency fixes
we can propose on a case by case basis and the user community can have
input as to whether the cost (app rework) is worth it without getting a
new feature at the same time.

But I think its clear that we *need* the microversions mechanism. So we
don't need to decide beforehand exactly what we're going to use it for
first. I think think its more important that we get a nova-spec
approved for the the first two parts - what it looks like from the
client point of view. And how we're going to implement it.



> 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
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

OpenStack-dev mailing list

Reply via email to