Designing APIs That Survive Production

The API that impresses in a demo and the API that survives production are different things. Production means retries, partial failures, angry mobile networks, concurrent writes and a partner integrating on a different schedule than you. Designing for that reality is a skill, and it is learnable.

Start with the contract. Define your API around resources and the states those resources move through, documented in a machine-readable format your consumers can generate clients from. A payment that exists across initiated, pending, settled and failed states tells integrators more than a wishy-washy 'status: string' ever will.

Idempotency is the rule that saves everyone. Network timeouts mean callers will retry, and your API must be safe to retry. Accept an idempotency key on state-changing requests, remember what you did with it, and return the original result for a repeated key. Payments APIs that skip this leak double-charges; the ones that enforce it quietly prevent a whole class of support tickets.

Pagination and performance are design decisions, not afterthoughts. Every list endpoint should page predictably and cap its results, and filters should mirror how users actually search. An endpoint that returns 100,000 rows because 'it just returns everything' is an endpoint that will be replaced by an angry consumer.

Errors should be honest. Return the right status codes, include a stable error code an integrator can branch on, and write messages a human can read. 'Something went wrong' is a failure of design; 'insufficient_funds: available 100, required 350' is a gift to every developer who has to handle it.

Version your API from the first public release. Change the contract as you learn — absolutely — but do it in a new version rather than silently breaking consumers. A documented deprecation path is the difference between trusted platform and unpredictable vendor.

Observability is your report card. Log every request with a trace id your consumers can quote in support, track latency and error rates per endpoint, and alert on the ones that matter. When a partner calls saying 'it failed at three in the morning', you want one search, not a forensic audit.

Finally, eat your own cooking. The best APIs are the ones the platform uses internally first — the dogfooding cycle exposes every design wart before strangers do. If your own product relies on the API blindly and survives, you have done the design right.