The API reference should be updated when compute APIs are modified (microversion is bumped, etc.). This page describes the guideline for updating the API reference.
The API reference consists of the following files.
api-ref/source/*.inc
api-ref/source/parameters.yaml
doc/api_samples/*
Each REST API is described in the text file (*.inc). The structure of inc file is as follows:
Title (Resource name)
Introductory text and context
The introductory text and the context for the resource in question should be added. This might include links to the API Concept guide, or building other supporting documents to explain a concept (like versioning).
API Name
REST Method
URL
Description
See the Description section for more details.
Response codes
Request
Response
API Name (Next)
The guideline for describing HTTP methods is described in this section. All supported methods by resource should be listed in the API reference.
Methods have to be sorted by each URI in the following order:
And sorted from broadest to narrowest. So for /severs it would be:
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)”
The following items should be described in each API. Or links to the pages describing them should be added.
ACTIVE
. The server is active.created_at
and id
in descending order by default)BUILDING
or shows another error status,
the request failed. Ensure you meet the preconditions then investigate
the compute node.export LC_ALL=en_US.UTF-8
in order to avoid incorrect unicode error.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:
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) |
In addition, the following explanations should be described.
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 request and response parameters have to be listed in the following order in each API in the text file.
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.
In the parameter file, define the required
field in each parameter.
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
).
If a parameter is available starting from a microversion,
the microversion must be described by min_version
in the parameter file.
However, if the minimum microversion is the same as a microversion
that the API itself is added, it is not necessary to describe the microversion.
For example:
aggregate_uuid:
description: |
The UUID of the host aggregate.
in: body
required: true
type: string
min_version: 2.41
This example describes that aggregate_uuid
is available starting
from microversion 2.41.
If a parameter is available up to a microversion,
the microversion must be described by max_version
in the parameter file.
For example:
security_group_rules:
description: |
The number of allowed rules for each security group.
in: body
required: false
type: integer
max_version: 2.35
This example describes that security_group_rules
is available up to
microversion 2.35 (and has been removed since microversion 2.36).
The order of parameters in the parameter file has to be kept as follows:
One or more examples should be provided for operations whose request and/or
response contains a payload. The example should describe what the operation
is attempting to do and provide a sample payload for the request and/or
response as appropriate.
Sample files should be created in the doc/api_samples
directory and inlined
by inclusion.
When an operation has no payload in the response, a suitable message should be included. For example:
There is no body content for the response of a successful DELETE query.
Examples for multiple microversions should be included in ascending microversion order.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.