Design

API design is the discipline of deliberately shaping what an API does and how it works — and the difference between a designed API and one that just happened is the difference between an API people love to use and one they tolerate or abandon. Design is where the most consequential decisions about an API get made: the resources it exposes, the operations it offers, the naming, the structure, the patterns, the consistency. These decisions, made early, determine whether the API will be intuitive or confusing, consistent or chaotic, a pleasure to integrate or a source of frustration. I’ve spent fifteen years arguing that design deserves far more attention than it usually gets, because design is where quality is born. You can document a badly designed API, you can govern it, you can support it — but you can’t undo the fact that it was designed poorly, because the design decisions are baked into the contract that consumers build on.

The building-blocks framing is how I made API design concrete and learnable, and it’s been foundational to my work. I wrote in 2014 about the common building blocks of API design — the recurring elements and patterns that well-designed APIs share, which can be studied, cataloged, and reused rather than reinvented every time. Design isn’t a mysterious art; it’s a craft with identifiable components and patterns, and learning those building blocks is how you get better at it. The point of cataloging the building blocks was to demystify design — to show that good API design follows recognizable patterns that any provider can learn and apply, rather than depending on rare individual genius. The most consistent, highest-quality APIs are the ones built from a shared vocabulary of well-understood design patterns, applied deliberately.

The design-first approach is the methodology I’ve advocated most consistently, and it’s been a genuine shift in how APIs get built. Design-first means you design the API contract — typically in OpenAPI — before you write the implementation, so the design is a deliberate decision rather than an accident of whatever the backend happened to produce. I’ve written about design-first versus prototype-first versus code-first, and about the honest reality that we will not convince everyone to go design-first, because it requires discipline and a change in workflow that many organizations resist. But the case for design-first is strong: when you design the contract first, you can review it, get feedback on it, mock it, and align stakeholders around it before committing to an expensive implementation. The design becomes the source of truth that drives everything downstream. Design-first is hard to adopt — I’ve been honest about that — but it’s the approach that produces the most deliberate, highest-quality APIs, because it makes design a conscious decision rather than a byproduct.

The most important design principle I’ve articulated is that your API should reflect a business objective, not a backend system. The most common design failure is exposing the internal database structure or the backend implementation directly, producing an API that’s organized around how the system happens to be built rather than around what consumers actually need to accomplish. Good design inverts this: you design around the consumer’s needs and the business objective, absorbing the complexity on the provider side so the consumer gets a clean, purposeful interface. I framed this in 2018 as a question of where the work lives — API design either has the provider do the work of creating a thoughtful interface, or it forces the consumer to do the work of figuring out a messy one. Every design decision either absorbs complexity on the provider side or exports it to every consumer, and good design absorbs it. The deeper question — what is more important, having an API or having a well-designed API — has an obvious answer: a poorly designed API is often worse than no API, because it actively frustrates the people who try to use it.

The connection between design and governance is where design becomes systematic rather than individual, and it’s a relationship I’ve mapped carefully. I wrote in 2017 that basic API design guidelines are your first step toward API governance — because governance is, in large part, the systematic application of good design across an organization. A design guide that captures your organization’s design standards, applied consistently through governance, is how you produce a portfolio of consistent, well-designed APIs rather than a sprawl of individually-designed ones. Design at the individual-API level is craft; design at the portfolio level, enforced through governance, is consistency. The two are connected: governance exists to scale good design across an organization, and good design is what governance is trying to produce. Design guides, style guides, and the governance that enforces them are all in service of making good design the default rather than the exception.

The design-time-versus-runtime tension is a current debate I’ve weighed in on, because the gateway-dominated reality threatens to devalue design. I wrote in 2023 about why design-time matters in a gateway-runtime-dominated reality — pushing back on the tendency to treat the runtime gateway as where everything happens and design-time as optional. The truth is that design-time is where the API is actually shaped, and no amount of runtime sophistication can fix a poorly-designed contract. The deepest thing I’d want anyone to take from all of this is that design is where API quality is determined, and that investing in deliberate, design-first, business-aligned, consistently-governed design is the highest-leverage thing you can do to produce APIs worth using. The technology to build APIs is widely available; what’s scarce is the discipline to design them well — to design around consumer needs rather than backend implementation, to design the contract first rather than letting it emerge from code, to apply consistent design patterns across a portfolio, and to treat design as the deliberate, consequential discipline it is rather than an afterthought. Design is where good APIs come from, and the organizations that take it seriously produce APIs that people genuinely want to use, while the ones that treat design as an afterthought produce APIs that work technically but fail the humans who have to integrate with them. Good design is the foundation everything else in the API lifecycle is built on.

Learnings

Guidance

Toolbox

Alignment

API Evangelist LLC

Design

References

Guidance Details

Explore more

Discover APIs