api-design

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.