On 2014年09月23日 17:12, Christopher Yeoh wrote:
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
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@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
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
