API Reference entry

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.

Content of the reference entry

Reference entries

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

Best practices for reference docs

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

examples: API reference of resource types

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!