Software Engineering · Jul 12, 2026 · 6 min read
Designing APIs that don't need documentation
Good documentation is a symptom of a good API. When endpoints are self-evident, error messages are instructions, and consistency is enforced, the docs become a changelog instead of a manual.
Wuese Philip
Full-Stack Software Engineer
I've interviewed for roles where the first take-home was 'integrate our API.' The best engineers I've hired finished in under an hour. Not because they were faster — because the API respected them.
An API that documents itself has four properties: predictable resource naming, errors that tell you what to do next (not just what went wrong), consistent pagination and filtering, and idempotency where it matters. Boring on purpose.
- Error: payment_method_invalid — 'Card was declined. Ask the customer to retry with a different card or update it via POST /customers/:id/payment_method.'
- GET /invoices?status=failed&from=2026-06-01&to=2026-07-01&page=2
The second property is the one teams skip. A status code and 'Internal error' is a shrug. An error that names the fix converts your support queue into a self-service flow. I've measured it: clear error copy cut our support tickets by a third.
Write the API your worst-day on-call wants to read at 3 a.m. If it reads well there, it reads well everywhere.
Found this useful?
The best way to say thanks is a project worth building.