Open Stack

On 2014年09月23日 17:12, Christopher Yeoh wrote:
> On Mon, 22 Sep 2014 09:29:26 +0000
> Kenichi Oomichi <oomichi at 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
>    issues.
>
> - 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
>      extension.
>
>    - 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.

Agree, consistency fixes should depend on the whether the cost is worth 
it or not, maybe we can't fix some inconsistency issues.
And definitely need micro-version for add tasks API and new server 
diagnostics. Also need micro-version to fix some bugs,
like https://bugs.launchpad.net/nova/+bug/1320754 and 
https://bugs.launchpad.net/nova/+bug/1333494.

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