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.