NovaAPIRef

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

Each of these are discreet steps. For review purposes, you should 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.

Once you believe you've completed a phase you should remove the applicable needs: tag for that phase from that file. That is the indication to the reviewers that work is done.

To find work that has not yet been done, search for the appropriate needs: comment in your nova source. For example:

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

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

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

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.

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, should we 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 documents to explain a concept (like versioning).