The reference section is a collection of short entries, arranged in alphabetical order. This template is for the individual reference entry that you create for a single endpoint.
The reference section is important for API documentation. New users will start with other documents to help them get going, but experienced users will refer more frequently to the reference section for the detailed information they need to make use of the API.
The reference section should contain a full listing of endpoints, methods, and parameters.
Each reference listing should contain:
- A general description of the endpoint, including what it's for, and what it can do
- The HTTP method, if applicable
- An example of the syntax
- All the parameters for the endpoint
For each parameter, include:
- An example request
- An example response
- The response schema
Each detailed reference entry should contain all the information readers need to know when using the feature.
For parameters, include:
- Name of the parameter
- Description of what the parameter does and when to use it
- Data type
- All the acceptable values, if there is a limited set of options
- Whether the parameter is required or optional
Differentiate the endpoint from other similar endpoints. If more than one endpoint or parameter can achieve the same result, explain which one to use in what situation, as each probably exists for a specific reason.
Include both syntax and a working example for each reference entry. Follow example code with extensive comments that explain how it works.
examples: API reference of resource types