API Fundamentals
An API is a behavioral contract, not a list of endpoints. Requirements before endpoints, consumer tasks before resources, granularity, ownership — and why internal APIs still need contracts.
Every lesson below names the consumers, the design question and the guarantee before recommending anything. Recommendations come with what they cost, when not to use them, and how they evolve.
An API is a behavioral contract, not a list of URLs. The contract includes shapes, errors, retry behavior, ordering, consistency and rate limits — everything a client is forced to assume, whether you documented it or not.
The first API artifact should be a list of questions answered, not a list of routes. Who consumes it, what can be retried, what is destructive, and what must stay compatible — endpoints fall out of those answers.
APIs exist for consumer tasks, not for the provider's data model. A mobile dashboard, a partner's invoice integration and an internal inventory call want different granularity, different fields and different guarantees from the same domain.
Too fine and every task takes ten round trips; too coarse and every call hauls a kitchen sink. Granularity is a per-consumer decision, and the network — not aesthetics — is what punishes getting it wrong.
The difference is not importance — it is who absorbs the cost of change. Public APIs trade evolution speed for a long compatibility promise; internal APIs may iterate faster only while every consumer is known and reachable.
Every API needs an owner, a version, a consumer list, an SLO and a deprecation status that a stranger can find in one place. An API nobody owns is a contract nobody keeps.
Consistency, predictability, explicitness, least surprise, good defaults, bounded operations. Principles earn their place as tie-breakers and review questions — not as absolutes that override a requirement.
Everything-POST, verb explosion, raw DB models as contracts, unbounded lists, 200-for-everything, frontend-only authorization, versioning nothing or versioning everything. Recognizing the pattern is faster than rediscovering the pain.