git:20260718.7c1285c to git:20260728.fac4544

---

name: api-design

description: Design HTTP and library APIs that are predictable, hard to misuse, and stable under growth. Use when creating or reviewing endpoints, public functions, or wire formats.

---

# API design

An API is a promise you keep for years. Design for the caller you cannot

see, then keep the promise boring.

## Method

1. **Start from the caller's sentence.** Write the code or request the

caller *wants* to make, before any implementation exists: `POST

/notebooks/{id}/share` or `client.notebooks.share(id)`. If the ideal call

is awkward to say, the design is wrong at the root.

2. **Name by domain, shape by convention.** Nouns for resources, verbs for

an API where "document", "file", and "source" mean one thing teaches

distrust of every name.

3. **Make the common case one call** with obvious defaults, and the rare

case possible with explicit options. Never make every caller pay a

configuration tax for flexibility one caller needs.

4. **Errors are API.** Every failure a caller can cause gets a distinct,

documented, stable error with: what went wrong, on which input, and what

to do. A caller should distinguish "you sent garbage" (4xx / typed

error), "we broke" (5xx), and "try later" without parsing prose.

5. **Design for the invalid states not to exist.** Required pairs travel in

one object; mutually exclusive options are one enum, not three booleans;

ids that must belong together are validated together. If misuse compiles

or returns 200, it will ship.

6. **Version from day one, break never.** Additive change is free (new

optional field, new endpoint). Breaking change (rename, meaning change,

removal) needs a version and a deprecation window. Before renaming a

field, remember: someone wrote a cron job against it.

7. **Paginate every list, bound every input.** Unbounded responses and

unbounded request sizes are outages on a delay.

## Litmus tests

- Can a caller learn the API from one example call plus type/shape

signatures, without reading your source?

- Is every operation idempotent that safely can be, and documented where it

cannot?

- Could you delete the docs page for defaults and have callers unaffected?

## Boundaries

one surprising-but-uniform surface is kinder than a half-migrated ideal.

Note the inconsistency you would fix, then follow the house style.