Difference between revisions of "NovaV3API"

Latest revision as of 23:31, 17 February 2013

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.

Nova v2 Fixes

Nova v3 Proposed Content

Demote Interfaces

Attributes on servers

admin_password
personalities

Promoted Interfaces