APIs as Products: Designing for Developers

Every API endpoint makes an implicit or explicit claim about three things: what it does, what shape its inputs and outputs take, and how long that behavior can be relied upon. Internal APIs, used only by teams inside the same company, can get away with treating this claim loosely, because the people affected by a change sit in the same building and can be told directly, or can simply read the updated code. External developer-facing APIs cannot. The developer building against your API today may not read your changelog, may not be in contact with anyone at your company, and may have shipped code six months ago that assumes today's behavior will still hold next year.

This asymmetry — the API provider can see and control every change, while the API consumer can only see the promise as it stood at the time they built against it — is the central design constraint of Layer 2. Good API design is, above all, a discipline of making explicit, keepable promises, and then keeping them.

This lesson introduces the Promise Tiers model: every part of an API surface sits in one of three concentric tiers, each with a different stability guarantee.

The critical discipline is not choosing the right tier once — it is being explicit, in the documentation itself, about which tier any given endpoint or field belongs to, and never silently promoting a Tier 3 experimental feature into de facto Tier 1 status just because developers started depending on it. A common and dangerous failure mode is the reverse: a company labels something "beta" to buy itself flexibility, developers adopt it heavily anyway because it is useful, and the company later discovers it cannot actually change the "beta" endpoint without breaking a large fraction of its ecosystem — the promise became real in practice even though it was never made real on paper.

Semantic versioning (a MAJOR.MINOR.PATCH numbering scheme) gives developers a fast, unambiguous signal about the size of a change: patch releases fix bugs without changing behavior developers rely on; minor releases add capability without breaking existing usage; major releases may break existing usage and require developers to take action. A deprecation policy — a published minimum time window between announcing that a feature will be removed and actually removing it — converts an abstract promise ("we won't surprise you") into an operational guarantee developers can plan around, budget engineering time for, and trust.

Together, these two mechanisms are what actually make the Tier 1/Tier 2 distinction meaningful. Without them, "stable" is just a marketing word.

Beyond stability, good API design reduces the total cost a developer pays to integrate successfully. Key elements include: consistent resource naming (so patterns learned on one endpoint transfer to others), predictable error formats (so failure handling code can be written once and reused), idempotency for operations that create or modify data (so a developer's retry logic after a network failure doesn't accidentally duplicate an action), sensible pagination defaults, and clear, enforced rate limits communicated in response headers rather than discovered only after being throttled. None of these are exotic; all of them are frequently skipped under deadline pressure, and each one that is skipped becomes a permanent tax on every developer who ever integrates.