API reference pages

API reference pages

There are two ways to document an API. Write it by hand with :::field, or connect an OpenAPI document and let the reference be generated.

By hand

:::field describes one parameter. Group the fields under headings for the request and the response.

## Request

:::field{name="limit" type="integer"}
How many pages to return. Between 1 and 100. Defaults to 50.
:::

:::field{name="cursor" type="string"}
The `next_cursor` from a previous response. Omit for the first page.
:::

## Response

:::field{name="pages" type="array" required="true"}
One object for each published page, in navigation order.
:::

Three attributes: name, type, and required="true". The body is the description, and it may contain any inline formatting.

Show the call in several languages

Pair the fields with a code group, so a reader sees the call in the language they use:

::::codegroup
```bash
curl -H "Authorization: Bearer $TOKEN" https://api.staleless.com/v1/pages
```
```python
requests.get(f"{API}/v1/pages", headers={"Authorization": f"Bearer {token}"})
```
::::

Warning

Do not invent SDK method names. Write the call the reader can actually make. A sample that names a method your library does not have costs more trust than the missing sample would have cost.

From OpenAPI

Connect an OpenAPI 3.0 or 3.1 document and the reference pages are generated from it: method and path, summary, description, authentication, parameters, request schema and example, responses, error models and schema links.

Staleless also diffs the document between syncs and classifies every change as additive, potentially breaking, or breaking. A change that needs documentation becomes an item in the inbox rather than a silent edit to a published page.

See OpenAPI for connecting one and for the sync schedule.

Which to choose

Situation	Use
You already publish an OpenAPI document	OpenAPI
A handful of endpoints, no specification	:::field
A specification exists but is incomplete	OpenAPI, plus hand-written pages beside it

The two live together. A generated reference and a hand-written guide are different pages, and the navigation puts them in the same section.