The API reference should be updated when placement 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
api-ref/source/samples/*
Each REST API is described in the text file (*.inc). The structure of inc file is as follows:
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 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) |
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
).
The order of parameters in the parameter file has to be kept as follows:
Todo
The guideline for request/response JSON bodies should be added.
Todo
The guideline for the introductory text and the context for the resource in question should be added.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.