Api Design

---
name: api-design
description: Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking.
---

# API design

An API is a promise you cannot withdraw once someone depends on it. Design accordingly: the cost of
getting it wrong is paid continuously by everyone who integrates.

## Model the domain, not the database

Expose concepts the consumer thinks in. An interface that mirrors internal table structure leaks
implementation, breaks whenever storage changes, and forces consumers to reconstruct meaning you
already had.

Name things as the domain names them. Consistency in naming, casing, date formats and identifier
style matters more than any individual choice being optimal — an interface that is uniformly
imperfect is learnable, and one that is inconsistently excellent is not.

## Errors are part of the contract

Most integrations spend most of their code on failure. Give it the same care as the success path:

- **Distinguish machine-readable code from human-readable message.** Consumers branch on the code;
  the message is for the developer reading logs.
- **Say what to do about it.** Retryable or not, and after how long.
- **Never leak internals** — stack traces and SQL in error bodies are a security finding as well as
  bad design.
- **Be consistent about which failures are which status.** Validation, authorization, and conflict
  are different situations and should never share a shape.

## Compatibility

Adding an optional field is safe. Removing a field, renaming one, tightening validation, changing a
default, or adding a required parameter are all breaking, and the last three break consumers who are
doing nothing wrong.

Version when you must break, and be explicit about how long the previous version lives. A
deprecation without a date is a deprecation nobody acts on.

Prefer expansion over versioning where possible: a new optional field costs a consumer nothing, a new
version costs them a migration.

## Pagination, filtering and limits

Any collection that can grow needs pagination from the first release — retrofitting it is a breaking
change to every consumer. Prefer cursors over offsets for anything that changes while being read;
offset pagination silently skips and duplicates records under concurrent writes.

State rate limits in the contract and communicate them in responses. An undocumented limit is
discovered in the consumer's production incident.

## Tooling

Specification and documentation: OpenAPI with Redocly, Stoplight, or Scalar; gRPC with protocol
buffers where the consumers are internal services, and similar.

Design review and testing: Postman, Insomnia, Bruno, and similar. Contract testing — Pact and
similar — is what catches a breaking change before a consumer does.

Generate the documentation from the specification and the specification from or alongside the code.
Hand-maintained API documentation is wrong within a release, and being confidently wrong is worse
for a consumer than being absent.

## Never

- Expose internal identifiers or storage structure through the interface.
- Return errors whose meaning must be inferred from the message text.
- Tighten validation on an existing endpoint and call it non-breaking.
- Ship a collection endpoint without pagination.