What Makes an API Good — API Design & Best Practices

An API is a user interface. The users just happen to be other programmers, and the interaction happens through JSON payloads and status codes instead of buttons and menus. Every discipline that applies to good UI design applies here too: minimize surprise, make the common case easy, make the uncommon case possible, and make the cost of a mistake visible immediately rather than three steps later. The difference that makes API design harder, not easier, than UI design is that a human using a confusing interface can pause, squint, and figure it out; a program calling a confusing API either fails loudly, fails silently, or works by accident until the day it doesn't.

This course is not going to hand you a checklist of rules to apply mechanically, because the honest answer to almost every API design question is "it depends on your consumers, your data, and what you're optimizing for." What it will give you is the judgment to make that call deliberately instead of by accident: knowing which tradeoffs a decision is actually making, not just which pattern looks familiar. A resource that returns 200 OK for a validation failure because someone copied a snippet without checking whether it fit the situation is not a small mistake — it is a decision nobody actually made, shipped anyway.

Good API design also has an asymmetric cost structure worth naming up front: the cost of designing carefully is paid once, by one team, before anything ships. The cost of designing carelessly is paid over and over, by every consumer who has to work around the inconsistency, guess at the undocumented behavior, or write defensive code because the API's own contract can't be trusted. A ten-minute naming discussion in a design review is cheap. A migration six months later to fix a naming inconsistency that's now baked into forty client integrations is not.

Analogy🏏Cricket

🏏 Think of it like cricket: A well-run scorecard is a kind of interface too, and it earns trust the same way a good API does — by being predictable in exactly the ways that matter. Every column means the same thing on every scorecard: runs is always runs, overs is always overs, and a fielder checking the total during a chase never has to wonder whether this particular scorer decided to count wides differently today. That predictability is what lets a captain glance at a board mid-innings and instantly know the required run rate without re-deriving what each number means from scratch. Now picture a scorer who, for one unusual match, decided extras would be folded into the batsman's own total instead of tracked separately, because it seemed simpler that afternoon. Nothing about the scorecard looks broken — the numbers still add up internally — but anyone consuming that scorecard from outside, comparing it to every other match they've ever watched, gets quietly wrong answers whenever they rely on their normal assumptions. The scorer's convenience became every viewer's hidden bug. This is the exact failure mode an API commits when a team decides, endpoint by endpoint, that a slightly different response shape or a slightly different error convention would be more convenient this time. The API still technically works. But every consumer who built correct assumptions from the rest of the API now silently breaks on the one endpoint that didn't honor them. Good design isn't the absence of clever ideas — it's the discipline to keep the interface boringly, reliably the same everywhere a consumer has learned to expect it.