Designing APIs That Outlive Their Authors

Durable APIs express the domain rather than the current database schema. Resource names, actions and errors should match concepts that clients understand. Internal refactoring is then possible without forcing every consumer to change.

Consistency is a feature. Similar operations should use the same pagination, filtering, authentication and error patterns. Predictability reduces client code and support work.

Compatibility should be planned before the first breaking request arrives. Additive fields are usually safer than changed meanings. Deprecations need dates, migration guidance, usage visibility and a period in which old and new behaviour can coexist.

Contracts should be machine-testable. Schemas, examples and consumer tests catch accidental breaks earlier than prose alone.

An API is a relationship between teams. Publish ownership, availability expectations, rate limits and incident channels. Return actionable errors with stable codes, and attach request identifiers that support investigation.

The best documentation explains workflows, not only endpoints. A new consumer should be able to complete a realistic task, understand failure modes and know how to move from a test environment to production.