Open Stack

# I changed the title for getting opinions from many projects.

2014-09-22 23:47 GMT+09:00 Anne Gentle <anne at openstack.org>:
>>
>> > -----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!
>
>
> I would greatly appreciate this style guide to be finalized for
> documentation purposes as well. Thanks for starting this write-up. I'd be
> happy to write it up on a wiki page while we get agreement, would that be
> helpful?

The wiki page of REST API style guide would be great,
thanks for joining into this :-)

>> 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
>
>
> Do you mean that the os- prefix should be dropped? Or that it should be
> maintained and added as needed?

The above samples contain two meanings:
 - extension names are added. ("os-security-groups:", "os-config-drive:")
 - their extensions are not cores. (v3 ones should contain "os-")

Their changes are Nova v3 API's ones, and now I have a question related to
your point.
Should we add extension names to each input/output attribute names?
How about naming them with snake_case only without extension names?

To be honest, I'm not sure yet extension name values for each attribute name.
Additional extension names make attribute names long and complex.
In addition, if we define Pecan/WSME as standard web frameworks, we should name
attributes with snake_case only because of Pecan/WSME restriction[1]. So we can
not name them with hyphens and colons which are including in current extension
attribute names.


>> (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
>
>
> Yes, I don't like the shoutyness of the ALL CAPS.
>
>>
>> (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)
>
> Do we have a list of "core" yet?

We have the list in the code:

nova/api/openstack/__init__.py
 62 # List of v3 API extensions which are considered to form
 63 # the core API and so must be present
 64 # TODO(cyeoh): Expand this list as the core APIs are ported to V3
 65 API_V3_CORE_EXTENSIONS = set(['consoles',
 66                               'extensions',
 67                               'flavor-extra-specs',
 68                               'flavor-manage',
 69                               'flavors',
 70                               'ips',
 71                               'os-keypairs',
 72                               'os-flavor-access',
 73                               'server-metadata',
 74                               'servers',
 75                               'versions'])

# As you see, some extensions in the above list contains "os-" even if cores
# because we have reverted them to v2 names through v2.1 API development.

but here also I have a question.
Is it necessary to define core by itself?
IIUC, DefCore is trying to define the core features of OpenStack and the tool
RefStack verifies these core behaviors through REST API.
Will they conflict in the future?

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

The above resource names also are against Pecan/WSME restrictions
because they contain hyphens.

>> (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
>
> Do you mean a 200 becomes a 201? That's a huge doc impact and SDK impact, is
> it worthwhile? If we do this change, the sooner the better, right?

No, these changes were v3 ones only, not current v2 API.
v3 API interfaces have disappeared now, and we will not change them without any
notifications(including Docs) because of backwards compatibilities.
So they don't affect to the existing SDKs and users.

The reason why I picked them up is that I hope we consider what is the best REST
API design. On the above samples, Nova v3 API was trying to return more accurate
status codes for showing each resource internal status.

I have a concern about this. If internal implementation of OpenStack
will be changed
like sync operation to async, should we change the status code also
for returning
accurate status code? That would make backwards incompatibilities. but
if not doing
that, status codes don't show accurate internal status.

So how about just using HTTP 200(OK) only for status codes?
That would give up providing accurate internal status to clients but backwards
backwards incompatibilities never happen.
# just one stupid idea :)

>> (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
>>
>
> Same here, sooner the better if these are better response codes.

The same as the above (3.1).

>> Any comments are welcome.
>>
>
> The TC had an action item a while back (a few months) to start an API style
> guide. This seems like a good start. Once the questions are discussed I'll
> get a draft going on the wiki.

Thanks again.
The REST API style guide would be nice for whole OpenStack projects.

and I have one more idea for making API consistency of whole OpenStack projects.
That is each rule of the style guide is implemented in Tempest.
Tempest has its own REST clients for many projects and we can customize them
for improving qualities. After defining the REST API style guide, we
can add each
rule to Tempest's base client class and apply it for all REST APIs
which are tested
by Tempest. We can keep consistent API for the existing projects and apply the
style guide to new projects also by this framework.

Thanks
Ken'ichi Ohmichi

---

[1]: http://lists.openstack.org/pipermail/openstack-dev/2013-May/009670.html