Difference between revisions of "NovaV3API"
| Line 13: | Line 13: | ||
== Rationale == | == Rationale == | ||
| + | During the Folsom release cycle some relatively minor seeming changes in the API, changing success values from 200 to 202, broke Tempest. Now that we've got substantial API coverage in Tempest it has become clear that minor changes for clarity and consistency can't be fixed in a stable API. However a number of these issues arrose during the end of the Folsom RC. Individually each one is easy enough to brush asside, but collectively they create substantial confusion in API structure. For long term adoption these should be fixed, as well as guidelines created to ensure all extensions accepted into [[OpenStack]] follow the same guidelines. | ||
| − | + | This will also give us an opportunity to align with the overall effort to make pagination and ordering consistent across [[OpenStack]] projects, making it possible and sane for an external API consumer to use the APIs. | |
| + | |||
| + | There was also a desire to promote a small number of core extensions that are widely enabled. | ||
== User stories == | == User stories == | ||
== Assumptions == | == Assumptions == | ||
| + | Upon the release of the v3 API, the v2 API will be deprecated, but it won't be removed for at least 1 major release based on our standard of deprecation. | ||
== Design == | == Design == | ||
== Implementation == | == Implementation == | ||
| + | The implementation has to go in a couple of discreet steps | ||
| + | |||
| + | === v2 API audit and best practice guide === | ||
| + | First step is to do a systematic audit of the existing v2 API looking for the right pattern of what status codes and usage is the best practices for API writing in the nova code. | ||
| + | |||
| + | In the process document bugs that need to change under the following tags: | ||
| + | * nova-v2-bug - straight up issue with API. e.g. Deleting non-existing resource returns 200 instead of 404 | ||
| + | * nova-v2-non-best-practice - issues where the best practices aren't followed. API uses a 200 when it should be a 202. API uses a non standard time format. API uses wrong return type. non best practices on ordering and sorting should be evaluated here as well. | ||
| + | * nova-v2-hole - API exists to set an object, but can't get it. Or can get an object but can't set it. | ||
| + | |||
| + | Bugs with these tags that can't be fixed in the v2 API should have reviews rejected against them until v3 API opens up. | ||
| − | v2 | + | === v2 Extension Promotion and Versioning === |
| + | A '''short''' list of extensions should be considered for promotion. This is not a free for all. This should be done in conjunction with v2 audit. | ||
| − | + | Additionally Extension versioning needs to be considered, as some extensions will need to change to support best practices. | |
| − | == | + | === v3 API openning === |
| + | Once the sweep is done, the extensions for promotion are decided, open up the v3 API tree. v2 API is copied over, and big push through bug queue to address the inconsistencies. | ||
| − | + | Tempest work will need to go in parallel to support the changes to nova in v3. | |
| − | == | + | == Test/Demo Plan == |
| − | + | All v3 APIs added must also see tests added to Tempest as part of this process. | |
== BoF agenda and discussion == | == BoF agenda and discussion == | ||
Revision as of 19:53, 2 November 2012
- Launchpad Entry: NovaSpec:nova-v3-api
- Created: 02 Nov 2012
- Contributors: Sean Dague
Summary
There are a number of inconsistencies in the Nova v2 API. These include error code inconsistencies (200 vs 202 returns), formatting inconsistencies (time stamps are in multiple formats), bugs, and straight up missing features that we assume the user has a tool to go directly to the database. We'll be creating a v3 API focused on cleaning up these changes, as well as promoting a few key extensions.
Release Note
There will be a new v3 API, and the v2 API will be deprecated, though still supported in the first release with v3.
Rationale
During the Folsom release cycle some relatively minor seeming changes in the API, changing success values from 200 to 202, broke Tempest. Now that we've got substantial API coverage in Tempest it has become clear that minor changes for clarity and consistency can't be fixed in a stable API. However a number of these issues arrose during the end of the Folsom RC. Individually each one is easy enough to brush asside, but collectively they create substantial confusion in API structure. For long term adoption these should be fixed, as well as guidelines created to ensure all extensions accepted into OpenStack follow the same guidelines.
This will also give us an opportunity to align with the overall effort to make pagination and ordering consistent across OpenStack projects, making it possible and sane for an external API consumer to use the APIs.
There was also a desire to promote a small number of core extensions that are widely enabled.
User stories
Assumptions
Upon the release of the v3 API, the v2 API will be deprecated, but it won't be removed for at least 1 major release based on our standard of deprecation.
Design
Implementation
The implementation has to go in a couple of discreet steps
v2 API audit and best practice guide
First step is to do a systematic audit of the existing v2 API looking for the right pattern of what status codes and usage is the best practices for API writing in the nova code.
In the process document bugs that need to change under the following tags:
- nova-v2-bug - straight up issue with API. e.g. Deleting non-existing resource returns 200 instead of 404
- nova-v2-non-best-practice - issues where the best practices aren't followed. API uses a 200 when it should be a 202. API uses a non standard time format. API uses wrong return type. non best practices on ordering and sorting should be evaluated here as well.
- nova-v2-hole - API exists to set an object, but can't get it. Or can get an object but can't set it.
Bugs with these tags that can't be fixed in the v2 API should have reviews rejected against them until v3 API opens up.
v2 Extension Promotion and Versioning
A short list of extensions should be considered for promotion. This is not a free for all. This should be done in conjunction with v2 audit.
Additionally Extension versioning needs to be considered, as some extensions will need to change to support best practices.
v3 API openning
Once the sweep is done, the extensions for promotion are decided, open up the v3 API tree. v2 API is copied over, and big push through bug queue to address the inconsistencies.
Tempest work will need to go in parallel to support the changes to nova in v3.
Test/Demo Plan
All v3 APIs added must also see tests added to Tempest as part of this process.
BoF agenda and discussion
Etherpad on this session from the Grizzly summit: https://etherpad.openstack.org/grizzly-nova-api
