Difference between revisions of "NovaAPIRef"

Latest revision as of 22:37, 14 November 2016

Verifying the Nova API Ref

This page explains the set of tasks we need to do to ensure that the API ref is properly up to date. Every file in api-ref/source/*.inc starts with the following comments at the top:

.. needs:method_verification
.. needs:parameter_verification
.. needs:example_verification
.. needs:body_verification

For review purposes, you should ideally submit 1 review per step per file. It's best if you self annotate reviews even when things didn't change (like links to where these can be verified) so it's easier for reviewers to process them.

Check https://etherpad.openstack.org/p/nova-api-ref for list of work in progress by reviewers. This shows work that has not yet been done by searching for the appropriate "needs: comment" in your nova source. For example:

$ grep "method_verification" api-ref/source/*

Keep an eye on open patches with the bp/api-ref-in-rst or bp/api-ref-in-rst-ocata tag for work already submitted for review.- https://review.openstack.org/#/q/status:open+topic:bp/api-ref-in-rst+project:openstack/nova

Claiming A Work Item

To claim a work item so that others don't start work on the same file and step, please do the following:

1. Create a branch in your local git repository
2. Remove the "needs:" line in the inc file for the step you are verifying
3. Commit and upload that change. You can mark the change as WIP in gerrit, add it as a prefix ("WIP:"), or do both. To make it easier for others to know what file you are working on, in the first line of your commit, please include the filename and the verification phase.
4. Once you've completed verification, don't forget to remove the WIP from the commit message.

.

Method Verification

This phase verifies that the HTTP methods are all correctly listed for each resource.

1. All supported methods should be listed (add any that aren't)
2. Remove methods which are erroneously listed
3. Reorder methods into the cannonical order

Reordering Methods

Methods should also be sorted in the following way:

1. GET
2. POST
3. PUT
4. PATCH (unused by Nova)
5. DELETE

And sorted from broadest to narrowest. So for /severs it would be

1. GET /servers
2. POST /servers
3. GET /servers/details
4. GET /servers/{server_id}
5. PUT /servers/{server_id}
6. DELETE /servers/{server_id}

This provides a common flow of list, create, show, update, delete for most resources, which is probably the most common operational pattern for most people.

Method Titles Spelling and Case

Make sure that the spelling and the case of method names in the title matches what is in the code. For instance, the title for the section on method "Get Rdp Console" should be "Get Rdp Console (os-getRDPConsole Action)" NOT "Get Rdp Console (Os-Getrdpconsole Action)" ^[1]

Parameter Verification

Verify the Request and Response parameter lists for each method. These are specified with the .. rest_parameters:: stanza.

Example:

.. rest_parameters:: parameters.yaml

  - field_name1: field_lookup1
  - field_name2: field_lookup2
  - ....

1. Ensure all fields are defined (header, path, query, body)
2. Ensure the correctness of type, required, description for all fields in parameters.yaml
   1. if a field was added in a microversion add min_version: to definition in parameters.yaml
3. Order the fields as follows
   1. header
   2. path
   3. query
   4. body
      1. top level object (i.e. server)
      2. required fields
      3. optional fields
      4. fields added in microversions (by the microversion they were added)

There are times when this might require splitting up fields because of definition changes, for instance: server_status is sometimes in the body as a required field, in the query as an optional field.

Parameters.yaml ordering

Attempt to keep the parameters.yaml file ordered as so:

1. by in type
   1. header
   2. path
   3. query
   4. body
2. then alphabetical by name

Note: because of the parameters merge there are a bunch of fields like id_# which were collisions of the use of id (and other common names). Try to change generic $names to things like $res_$name (or $res_$name_$in) defining parameters. For instance:

id (for a server) -> server_id id (in the path for a server) -> server_id_path

Example Verification

We want to make sure all request and response have valid sample files. These come from the /doc/api_samples/ directory.

1. Does the sample included actually match with the request / response in question
2. If there is no sample, we should create one
3. Does the example have an English explanation of what it is attempting to do (or an expression of what was done and then the request returned)

Each API should have request and response information when applicable. When a response has no JSON context and relies on the HTTP response code (e.g. such as a DELETE), a suitable message should be included. For example:

There is no body content for the response of a successful DELETE query.

Body Verification

This is more qualitative, and expected to be done last. The point of this is to verify that the introductory text for every file makes sense and sets up the context for the resource in question. This might include links to the API Concept guide, or building other supporting

1. ↑ [1], Example of method section title