# Write an API reference page

Use this when someone hands you an endpoint, an operation from an OpenAPI
document, or a request and response pair, and wants the reference page a
consumer reads before calling it.

## Steps

1. Lead with what the endpoint does and when to call it, in one paragraph.
2. Document the request: method, path, every parameter with its type,
   whether it is required, its default and an example value.
3. Document each response by status code, with a realistic example body.
4. List the errors a caller can act on, and what to do about each.
5. Close with one complete request example a consumer can paste and run.

## What not to do

Do not invent fields that the definition does not carry. Where the
definition is silent, say so rather than guessing.

---
name: write-an-api-reference-page
description: 'Turns an endpoint definition into reference documentation a consumer can act on without asking questions.'
---

# Write an API reference page

Use this when someone hands you an endpoint, an operation from an OpenAPI
document, or a request and response pair, and wants the reference page a
consumer reads before calling it.

## Steps

1. Lead with what the endpoint does and when to call it, in one paragraph.
2. Document the request: method, path, every parameter with its type,
   whether it is required, its default and an example value.
3. Document each response by status code, with a realistic example body.
4. List the errors a caller can act on, and what to do about each.
5. Close with one complete request example a consumer can paste and run.

## What not to do

Do not invent fields that the definition does not carry. Where the
definition is silent, say so rather than guessing.