On 09/22/2014 05:29 AM, Kenichi Oomichi wrote:
-----Original Message-----
From: Alex Xu [mailto:x...@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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
