Add the guideline to write API reference
Adapted from the wiki: https://wiki.openstack.org/wiki/NovaAPIRef Compute API reference: https://developer.openstack.org/api-ref/compute/ Placement API reference: https://developer.openstack.org/api-ref/placement/ Change-Id: I78ded463142fc50af3b77721500ed190448632c7
This commit is contained in:
Takashi NATSUME
Matt Riedemann
parent
710ef9f4c8
commit
7a7c2fe142
233
doc/source/contributor/api-ref-guideline.rst
Normal file
233
doc/source/contributor/api-ref-guideline.rst
Normal file
@ -0,0 +1,233 @@
|
||||
=======================
|
||||
API reference guideline
|
||||
=======================
|
||||
|
||||
The API reference should be updated when compute or placement APIs are modified
|
||||
(microversion is bumped, etc.).
|
||||
This page describes the guideline for updating the API reference.
|
||||
|
||||
API reference
|
||||
=============
|
||||
|
||||
* `Compute API reference <https://developer.openstack.org/api-ref/compute/>`_
|
||||
* `Placement API reference <https://developer.openstack.org/api-ref/placement/>`_
|
||||
|
||||
The guideline to write the API reference
|
||||
========================================
|
||||
|
||||
The API reference consists of the following files.
|
||||
|
||||
Compute API reference
|
||||
---------------------
|
||||
|
||||
* API reference text: ``api-ref/source/*.inc``
|
||||
* Parameter definition: ``api-ref/source/parameters.yaml``
|
||||
* JSON request/response samples: ``doc/api_samples/*``
|
||||
|
||||
Placement API reference
|
||||
-----------------------
|
||||
|
||||
* API reference text: ``placement-api-ref/source/*.inc``
|
||||
* Parameter definition: ``placement-api-ref/source/parameters.yaml``
|
||||
* JSON request/response samples: ``placement-api-ref/source/samples/*``
|
||||
|
||||
Structure of inc file
|
||||
---------------------
|
||||
|
||||
Each REST API is described in the text file (\*.inc).
|
||||
The structure of inc file is as follows:
|
||||
|
||||
- Title
|
||||
|
||||
- API Name
|
||||
|
||||
- REST Method
|
||||
|
||||
- URL
|
||||
- Description
|
||||
- Normal status code
|
||||
- Error status code
|
||||
- Request
|
||||
|
||||
- Parameters
|
||||
- JSON request body example (if exists)
|
||||
- Response
|
||||
|
||||
- Parameters
|
||||
- JSON response body example (if exists)
|
||||
- API Name (Next)
|
||||
|
||||
- ...
|
||||
|
||||
REST Method
|
||||
-----------
|
||||
|
||||
The guideline for describing HTTP methods is described in this section.
|
||||
All supported methods by resource should be listed in the API reference.
|
||||
|
||||
The order of methods
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Methods have to be sorted by each URI in the following order:
|
||||
|
||||
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}
|
||||
|
||||
Method titles spelling and case
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The spelling and the case of method names in the title have to match
|
||||
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)"
|
||||
|
||||
Response codes
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The normal response codes (20x) and error response codes
|
||||
have to be listed. The order of response codes should be in ascending order.
|
||||
The description of typical error response codes are as follows:
|
||||
|
||||
.. list-table:: Error response codes
|
||||
:header-rows: 1
|
||||
|
||||
* - Response codes
|
||||
- Description
|
||||
* - 400
|
||||
- badRequest(400)
|
||||
* - 401
|
||||
- unauthorized(401)
|
||||
* - 403
|
||||
- forbidden(403)
|
||||
* - 404
|
||||
- itemNotFound(404)
|
||||
* - 409
|
||||
- conflict(409)
|
||||
* - 410
|
||||
- gone(410)
|
||||
* - 501
|
||||
- notImplemented(501)
|
||||
* - 503
|
||||
- serviceUnavailable(503)
|
||||
|
||||
Parameters
|
||||
----------
|
||||
|
||||
Parameters need to be defined by 2 subsections.
|
||||
The one is in the 'Request' subsection, the other is in the 'Response'
|
||||
subsection. The queries, request headers and attributes go in the 'Request'
|
||||
subsection and response headers and attributes go in the 'Response'
|
||||
subsection.
|
||||
|
||||
The order of parameters in each API
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The request and response parameters have to be listed in the following order
|
||||
in each API in the text file.
|
||||
|
||||
1. Header
|
||||
2. Path
|
||||
3. Query
|
||||
4. Body
|
||||
|
||||
a. Top level object (i.e. server)
|
||||
b. Required fields
|
||||
c. Optional fields
|
||||
d. Parameters added in microversions (by the microversion they were added)
|
||||
|
||||
Parameter type
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
The parameters are defined in the parameter file (``parameters.yaml``).
|
||||
The type of parameters have to be one of followings:
|
||||
|
||||
* ``array``
|
||||
|
||||
It is a list.
|
||||
|
||||
* ``boolean``
|
||||
* ``float``
|
||||
* ``integer``
|
||||
* ``none``
|
||||
|
||||
The value is always ``null`` in a response or
|
||||
should be ``null`` in a request.
|
||||
|
||||
* ``object``
|
||||
|
||||
The value is dict.
|
||||
|
||||
* ``string``
|
||||
|
||||
If the value can be specified by multiple types, specify one type
|
||||
in the file and mention the other types in the description.
|
||||
|
||||
Required or optional
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In the parameter file, define the ``required`` field in each parameter.
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 85
|
||||
|
||||
* - ``true``
|
||||
- The parameter must be specified in the request, or
|
||||
the parameter always appears in the response.
|
||||
* - ``false``
|
||||
- It is not always necessary to specify the parameter in the request, or
|
||||
the parameter does not appear in the response in some cases.
|
||||
e.g. A config option defines whether the parameter appears
|
||||
in the response or not. A parameter appears when administrators call
|
||||
but does not appear when non-admin users call.
|
||||
|
||||
If a parameter must be specified in the request or always appears
|
||||
in the response in the micoversion added or later,
|
||||
the parameter must be defined as required (``true``).
|
||||
|
||||
The order of parameters in the parameter file
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The order of parameters in the parameter file has to be kept as follows:
|
||||
|
||||
1. By in type
|
||||
|
||||
a. Header
|
||||
b. Path
|
||||
c. Query
|
||||
d. Body
|
||||
|
||||
2. Then alphabetical by name
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. TODO::
|
||||
|
||||
The guideline for request/response JSON bodies should be added.
|
||||
|
||||
Body
|
||||
----
|
||||
|
||||
.. TODO::
|
||||
|
||||
The guideline for the introductory text and the context for the resource
|
||||
in question should be added.
|
||||
|
||||
Reference
|
||||
=========
|
||||
|
||||
* `Verifying the Nova API Ref <https://wiki.openstack.org/wiki/NovaAPIRef>`_
|
||||
* `The description for Parameters whose values are null <http://lists.openstack.org/pipermail/openstack-dev/2017-January/109868.html>`_
|
||||
* `The definition of "Optional" parameter <http://lists.openstack.org/pipermail/openstack-dev/2017-July/119239.html>`_
|
||||
@ -210,6 +210,7 @@ looking parts of our architecture. These are collected below.
|
||||
contributor/development-environment
|
||||
contributor/api
|
||||
contributor/api-2
|
||||
contributor/api-ref-guideline
|
||||
contributor/blueprints
|
||||
contributor/code-review
|
||||
contributor/documentation
|
||||
|
||||
Loading…
Reference in New Issue
Block a user