API contributor guide


OpenStack API working group has defined a guideline to follow for API documentation when a project provides a REST API service. API documentation information comes from RST source files stored in the project repository, that when built, generate HTML files. More details about the OpenStack API documentation can be found at: https://docs.openstack.org/doc-contrib-guide/api-guides.html.

StarlingX API Reference documentation exists in the following projects:

  • starlingx/config: StarlingX System Configuration Management

  • starlingx/docs: StarlingX Documentation

    • stx-python-cinderclient // only StarlingX-specific extensions to Cinder API are documented here

    • stx-nova // only StarlingX-specific extensions to Nova API are documented here

    • stx-glance // only StarlingX-specific extensions to Glance API are documented here

    • stx-neutron // only StarlingX-specific extensions to Neutron API are documented here

  • starlingx/distcloud: StarlingX Distributed Cloud

  • starlingx/fault: StarlingX Fault Management

  • starlingx/ha: StarlingX High Availability/Process Monitoring/Service Management

  • starlingx/metal: StarlingX Bare Metal and Node Management, Hardware Maintenance

  • starlingx/nfv: StarlingX NFVI Orchestration

Directory Structures

The directory structure of the API Reference documentation under each StarlingX project repository is fixed. Here is an example showing starlingx/config StarlingX System Configuration Management

└── source
    ├── api-ref-sysinv-v1-config.rst
    ├── conf.py
    └── index.rst

The initial modifications and additions to enable the API Documentation service in each StarlingX project are as follows:

  • .gitignore modifications to ignore the building directories and HTML files for the API reference

  • .zuul.yaml modifications to add the jobs to build and publish the api-ref document

  • api-ref/source directory creation to store your API Reference project directory

  • api-ref/source/conf.py configuration file to determine the HTML theme, Sphinx extensions and project information

  • api-ref/source/index.rst source file to create your index RST source file

  • doc/requiremets.txt modifications to add the os-api-ref Sphinx extension

  • tox.ini modifications to add the configuration to build the API reference locally

See starlingx/config [Doc] OpenStack API Reference Guide as an example of this first commit: https://review.opendev.org/#/c/603258/

Creating the RST Source File

Once the API Documentation service has been enabled, you create the RST source files that document the API operations under the same API Reference documentation project directory. The following shows the RST source file for the starlingx/config StarlingX System Configuration Management: Configuration API v1

└── source
        └── api-ref-sysinv-v1-config.rst

Creating the Index File

After providing the RST source file as shown in the previous example, you add the index.rst file. This file provides captioning, a brief description of the document, and the table-of-contents structure with depth restrictions. The index.rst file resides in the same folder as the RST source file.

Here is an example using the starlingx/config StarlingX System Configuration Management: Configuration API v1:


The syntax of the index.rst file is fixed. Following shows the index.rst file used in the starlingx/config:

stx-config API Reference
StarlingX System Configuration Management

.. toctree::
   :maxdepth: 2


Following are explanations for each of the four areas of the index.rst file:

  • Reference title: Literal title that is used in the rendered document. In this case it is “stx-config API Reference”.

  • Reference summary: Literal summary of the rendered document. In this case it is “StarlingX System Configuration Management”.

  • Table-of-Contents tree structure and depth parameters: The directive to create a TOC and to limit the depth of topics to “2”.

  • RST source file root name: The source file to use as content. In this case, the file reference is “api-ref-sys-v1-config”. This references the api-ref-sys-v1-config.rst file in the same folder as the index.rst file.


Following is the syntax for each REST METHOD in the RST source file (e.g. api-ref-sys-v1-config.rst).

Modifies attributes of the System object
.. rest_method:: PATCH /v1/isystems

<  TEXT - description of the overall REST API >

**Normal response codes**

< TEXT - list of normal response codes  >

**Error response codes**

< TEXT – list of  error response codes  >

**Request parameters**

.. csv-table::
   :header: "Parameter", "Style", "Type", "Description"
   :widths: 20, 20, 20, 60
   "ihosts (Optional)", "plain", "xsd:list", "Links for retreiving the list of hosts for this system."
   "name (Optional)", "plain", "xsd:string", "A user-specified name of the cloud system. The default value is the system UUID."
   < etc. >
< verbatim list of an example REQUEST body >
       "path": "/name",
       "value": "OTTAWA_LAB_WEST",
       "op": "replace"
       "path": "/description",
       "value": "The Ottawa Cloud Test Lab - West Wing.",
       "op": "replace"
**Response parameters**

.. csv-table::
   :header: "Parameter", "Style", "Type", "Description"
   :widths: 20, 20, 20, 60
   "ihosts (Optional)", "plain", "xsd:list", "Links for retreiving the list of hosts for this system."
   "name (Optional)", "plain", "xsd:string", "A user-specified name of the cloud system. The default value is the system UUID."
   < etc. >
< verbatim list of an example RESPONSE body >
   "isystems": [
            "links": [
                "href": "",
                "rel": "self"
                "href": "",
                "rel": "bookmark"
            "description": "The Ottawa Cloud Test Lab - West Wing.",
            "software_version": "18.03",
            "updated_at": "2017-07-31T17:44:06.051441+00:00",
            "created_at": "2017-07-31T17:35:46.836024+00:00",

Building the Reference Documentation

To build the API reference documentation locally in HTML format, use the following command:

$ tox -e api-ref

The resulting directories and HTML files looks like:

├── doctrees
│   ├── api-ref-sysinv-v1-config.doctree
└── html
    ├── api-ref-sysinv-v1-config.html
    ├── index.html
    └── _static

Closing Out a Bug or Story

If you are modifying a document as a result of a defect or feature that is associated with a StoryBoard Story or Launchpad Bug, you must take steps to link your submission (Gerrit Review) to the story or bug.

To link a story, add the following lines in your commit message. Be sure to use the actual story ID and task ID:

  • Story: $story_id

  • Task: $task_id

Following is an example that links a Gerrit Review with Story 2003375 and Task 2444:

Change the tox.ini directory regarding tox.ini dependencies

Story: 2003375
Task: 24444

NOTE: You must provide a blank line before the lines used to identify the story and the task. If you do not provide this line, your submission will not link to the Storyboard’s story.

To link a bug, add the approprite lines in your commit message. Be sure to provide the actual bug numbers:

  • Closes-Bug: $bug_id

  • Partial-Bug: $bug_id

  • Related-Bug: $bug_id

If your fix requires multiple commits, use “Partial-Bug” for all the commits except the final one. For the final commit, use “Closes-Bug”.

Following is an example commit message that closes out bug 1804024:

AIO Hardware Requirements: Updated AIO HW requirements.

Added Small HW form factor information simplex/duplex
AIO hardware requirements.

Closes-Bug: #1804024

When you associate a story or bug with a Gerrit review, Gerrit automatically updates the status of the story or bug once the commit is merged. Again, be sure to provide a blank line just before the line identifying the bug.

You can find more information on the StarlingX code submission guidelines on the wiki.

To see the list of defects against StarlingX, see the Launchpad Application.

Viewing the Rendered Reference Documentation

To view the rendered HTML API Reference document in a browser, open up the index.html file.

NOTE: The PDF build uses a different tox environment and is currently not supported for StarlingX.