Open Stack

On 09/22/2014 05:29 AM, Kenichi Oomichi wrote:
>> -----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.

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

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

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

++ 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.

Best,
-jay

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