The Quiet Work of Good API Design

Nobody writes blog posts about APIs that work well. The Stripe API, the Vercel API, the GitHub API — you use them, they do what you expect, and you move on. The design recedes. That's the goal. But when an API is poorly designed, you feel it constantly. You open the docs every time you make a call because you can never remember the parameter order. You write wrappers around wrappers because the response shape doesn't match the shape of your domain. You dread the integration because you know it will be a day of archaeology. This is the quiet work of API design: making something that developers stop thinking about. The principle that matters most. Consistency. Not cleverness, not minimalism, not expressiveness — consistency. If you paginate one endpoint with page and per_page, every endpoint should use page and per_page. If your timestamps are ISO 8601 in one resource, they're ISO 8601 everywhere. If errors return { error: { message: "..." } }, that's what they always return. Consistency lets developers build a mental model. Once they understand one part of your API, they can predict the rest. That's worth more than any amount of elegant design. Resource shapes are contracts. This is the one we see violated most often, especially in fast-moving startups. The shape of your API response isn't just a technical detail — it's a contract with every developer who integrates with you. Breaking changes should be rare, versioned, and announced far in advance. "We added a field" is fine. "We renamed a field" is a breaking change. "We changed the type of a field" is a breaking change. Treat them accordingly. We've seen companies lose enterprise customers not because their product was bad, but because a surprise API change broke an integration on a Friday afternoon. Trust is hard to rebuild. The documentation is part of the design. An API without documentation is like a product without a UI. The interface exists, but no one can use it effectively. Good documentation isn't just reference material. It's onboarding. It's the "hello world" that works first try. It's the explanation of why, not just what. It's the error message that tells you what you did wrong and how to fix it. If you can't document a decision clearly, the decision might be wrong. What we try to do. When we design APIs at Crafyne, we start by writing the documentation before we write the code. Describing the interface forces you to confront the awkward decisions before they're hardened into endpoints. It's slower in the short run. It's much faster overall.