Designing From the Consumer Inward — API Design & Best Practices

The most common way an API ends up hard to use is not a single bad decision — it's designing outside-in from the database. A team builds the tables first, then writes an ORM model for each table, then exposes each model as an endpoint, and the resulting API is a faithful, well-organized map of the database schema that has almost nothing to do with what a consumer is actually trying to accomplish. The consumer wanted to cancel a subscription in one call; the API makes them read a `subscriptions` row, patch three fields across two tables in the right order, and hope they got the sequencing right, because that's how the schema happened to be normalized.

Designing from the consumer inward means starting from a different question entirely: what is the consumer trying to accomplish, and what is the smallest, clearest interaction that accomplishes it? Only after that's answered do you work backward to how the server fulfills it — which tables get touched, which internal services get called, in what order. The consumer-facing shape and the internal implementation are allowed to look completely different, and in a well-designed API, they usually do.

This isn't a purely academic distinction. A schema-first API tends to grow more brittle over time, because every internal refactor — splitting a table, normalizing a field differently, moving a computation from write-time to read-time — has a direct, visible chance of changing the public contract, since the contract was never actually separate from the schema to begin with. A consumer-first API has a real seam between the two, and that seam is exactly what lets you refactor internals freely without every change becoming a breaking change for someone outside your team.

Analogy🏏Cricket

🏏 Think of it like cricket: A scoreboard operator at a stadium doesn't build the giant screen display by first deciding how the internal scoring software organizes its data tables, then putting one screen panel per table. They start from the opposite direction: what does a spectator in the stands, glancing up mid-over, actually need to know right now? The current total, the required rate if it's a chase, the last six balls, the not-out batsmen's scores — a small, carefully chosen set of numbers assembled from wherever the underlying system happens to store them, restructured entirely for what a glance needs to answer. The internal scoring software might track dozens of granular fields per delivery — bowler's exact release point data, ball-tracking coordinates, a dozen categories of extras — but almost none of that appears on the big screen, because the big screen was designed around the question a spectator is actually asking, not around what the internal system happens to record. If the scoreboard were instead organized by internal database table, a spectator would see a wall of numbers technically accurate but useless for the one question they actually have. An API built by exposing internal tables one-for-one commits the identical error: it answers a question about internal structure instead of the question a consumer is actually asking, and every consumer pays the translation cost the scoreboard operator absorbed on everyone's behalf instead.