APIs are one of those things that look easy until they have been in production for three years. The interface decisions made on day one calcify quickly — downstream consumers build on them, internal teams couple to them, and even the names of fields become contracts that cannot be casually changed. The design discipline that pays back is unglamorous and well-known, but it is rarely fully applied until after the team has lived with an API that did not have it.
Versioning Is A Promise To Consumers
Microsoft's API design guidance and Google's API Design Guide both anchor on the same point: an API version is a promise about backward compatibility, not a release tag. Pick a versioning strategy — URL, header, or content negotiation — document it, and stick to it. Most APIs that get into trouble are APIs where the team treated versioning as something they would figure out later.
Error Semantics Are A Product Surface
Errors are the part of the API surface that consumers see when something has already gone wrong, and the experience should be designed accordingly. Stripe's error reference is a useful gold standard: every error has a stable code, a human-readable message, a doc URL, and a category that tells the caller whether to retry, escalate, or surface to the user. Error semantics that are afterthoughts produce support tickets that the API team eventually pays for, several times over.
Idempotency For Mutating Operations
Any mutating endpoint that can be retried needs to be idempotent. The pattern is well-codified: the client sends an idempotency key on every mutation, the server stores the key with the response for some retention window, and repeated requests return the original response rather than executing the operation twice. The IETF's Idempotency-Key Header draft is the right reference for the wire-protocol details. The implementation is the easy part. The discipline of applying it to every relevant endpoint is the hard part.
Pagination, Filtering, And The Long Tail
List endpoints accumulate scope over time and rarely get redesigned. The right move is to pick a pagination scheme up front — cursor-based pagination is almost always the right answer for production systems — and to treat filter and sort parameters as a first-class part of the contract. The OpenAPI Initiative's specification documentation is a useful reference for documenting these surfaces in a way that survives team turnover.
Authentication, Rate Limits, And The Operational Surface
Authentication is part of the API design, not a deployment concern. OAuth 2.1 with rotating short-lived tokens, scopes modeled as resource-action pairs, and a clear story for service-to-service auth is the durable pattern. Rate limits should be communicated through response headers (limit, remaining, reset) rather than left for consumers to reverse engineer. The OWASP API Security Top 10 is the canonical reference for the security surface.
Documentation As A Living Artifact
The best APIs are the ones with documentation that the team treats as a living artifact: generated from the same source-of-truth as the implementation, exercised in CI, and updated alongside the code. Stripe, GitHub, and Twilio all converge on this pattern, and it is the hallmark of API surfaces that age well.
Key Takeaways
- API versioning is a backward-compatibility promise — pick a strategy and stick to it
- Errors are a product surface; design them like one
- Idempotency on mutating endpoints is non-negotiable for production
- Cursor pagination is the right default for list endpoints
- Authentication, scopes, and rate limits belong in the API contract, not the deployment
- Documentation generated from a single source of truth ages with the code