Five common sections in REST API documents
1. Description of resources
Resources (information) are the target of an HTTP request.
2. Endpoints and methods
- Endpoints: how to access the resource.
- HTTP methods: the allowed interactions with the resource.
3. Parameters
Options for retrieving resources that can be passed along with the endpoint (such as specifying the response format or the amount returned) to influence the response.
4. Example of a request
An example of a request that uses the endpoint and shows configured parameters.
5. Example of a response and schema
- Example of a response: an example of a response from the request example.
- Example of a schema: defines all possible elements in the response.