Content¶
First you should generate or write the reference information including:
Method (GET/PUT/POST/PATCH/HEAD/DELETE)
Resource (Identified by the URL)
Request parameters, type and description including whether it is optional
Request headers including media-type, content-type, accept, and others
Response headers (for some APIs)
Responses including types and description
Example request body and headers
Example response body and headers
Status codes: successful request and error responses
Resource model: describes data types that can be consumed and produced by operations.
The resource model may be created with either a parameters.yaml file or with the OpenAPI Definitions object Swagger is governed by the OpenAPI initiative.
See authoring tools below for more information on writing or generating the parameters information.
Also important is the conceptual or narrative information that explains the REST API and what it provides as a service.
Documentation should also offer information about the concepts for each resource, such as server status or volume status.
Documentation should provide a discussion about the consistency model the service provides and synchronous or asynchronous behavior for certain methods.
As guidance, here is a list of topics to ensure you include in your API docs beyond the reference information.
Authentication
Faults (synchronous and asynchronous)
Limits (rate limits, absolute limits, calls to find out limits)
Constraints (min and max for certain values even if chosen by provider)
Content compression
Encoding
Links and references
Pagination
Filtering
Sorting
Formats (request, response)
Endpoints, versions and discoverability
Capabilities and discoverability
Term definitions (by adding to the OpenStack glossary sourced in openstack-manuals)
Status or state values
Hierarchy information
Quotas
Extensions
These topics should be written in RST and built with either Sphinx or alongside the generated OpenAPI using the Pecan app described below. The outline itself is not prescribed since REST APIs vary widely.
