API Design: A Complete Guide
The decisions behind an HTTP API, in the order they arrive. Resources, methods, status codes, errors, pagination, idempotency and rate limits.
You have already made these decisions. Every API has a resource model, a status code for a rejected write and a shape for its error bodies, whether or not anyone chose them on purpose.
The question is whether they were decided once and written down, or a hundred times by different people under deadline pressure. This guide covers the decisions themselves, in the order they arrive, and what each one costs when you get it wrong.
The decisions arrive in an order
Design decisions are not a checklist you can work through in any sequence, because the early ones constrain the later ones.
That order is also why so much design debt is expensive. Changing a pagination style touches every list endpoint, and changing a resource model touches every URL you have published.
Why the specification is not the design
An OpenAPI document describes an interface precisely, and it is completely indifferent to whether the interface is any good.
You can write a valid document for an API with three different pagination styles, five error shapes and a POST /doThing in the middle of it. The file will validate, the reference documentation will render and the mock server will answer. None of those tools has an opinion about the decisions underneath.
So the specification is where a decision gets recorded and checked, and it is not where the decision gets made. The OpenAPI guide covers the format itself, and this guide covers what you put in it.
The cost of deciding twice
Almost every decision here has more than one defensible answer, and the difference between the answers is usually smaller than the difference between deciding once and deciding repeatedly.
Cursor pagination and offset pagination both work. What does not work is one collection paged by cursor, a second by page number and a third returning everything. A consumer writes the pagination loop three times, and the third one is where the bug lives.
This is the argument that runs through the whole guide. Where two options are genuinely close, the text says so and moves on to the thing that matters, which is applying whichever you picked everywhere.
The short answer
If you take one rule from this guide, take this one. Decide each of these once, write the decision into the contract rather than into a wiki page, and put a check in the way of the next person who decides differently.
The rest of the guide is that rule taken apart.
| Chapter | Answers |
|---|---|
| Resources and URLs | Nouns over verbs, when nesting helps and when it traps you |
| Methods and status codes | What each method promises, and which code sets which expectation |
| Designing API errors | One shape for every failure, and a way out of each one |
| Actions that are not CRUD | Cancel, publish, retry, search, and the cost of each modelling |
| Pagination, filtering and sorting | Offset against cursor, and what each costs under concurrent writes |
| Idempotency and retries | Why callers retry, and what an idempotency key actually promises |
| Rate limits | What a limit tells a caller, and the headers that carry it |
| Consistency across an API | Why consistency has to be a mechanism rather than an intention |
| Design for the client you now have | What changes when the caller reads your description at runtime |
| Choosing a design tool | The criteria that separate an editor from a design workflow |
Three neighbouring subjects live in other guides. The document format is covered in the OpenAPI guide, and what to do when a decision has to change is covered in API versioning. How a decision becomes an enforced rule runs through consistency into the tooling. For a one-page summary of the same ground, the API design principles post is the short version this guide expands.
In Routebase
Routebase is a structured API designer, so a decision lands in a form rather than in YAML, and the OpenAPI document is what it is stored as.
The decisions in this guide surface in three places in the product. Folders and tags carry the resource model, components and the organisation-level shared library carry the shapes you reuse, and the style guide turns a convention into a check that runs while you type. Start with the Endpoints guide in the product documentation, or read on. The API design feature page has the short version of how the designer fits into the rest of the lifecycle.
Frequently asked questions
What is API design?
API design is the set of decisions that fix what an HTTP interface promises before any of it is built. Those decisions cover which resources exist and what they are called, which method does what, and which status code comes back. They also cover what an error looks like, how a long list is paged and what happens when a caller retries. Writing the specification records those decisions, and it does not make them for you.
What are the most important API design decisions?
Four of them shape everything that follows. The resource model decides what your URLs can express, and the method and status code semantics decide what a caller may assume. The error format decides how a client recovers, and the pagination style decides whether a list endpoint survives its own growth. Each of those is expensive to change later, because each one is visible to every consumer.
Should you design an API before writing code?
Designing first is worth it when more than one team depends on the result, because the contract becomes something they can build against in parallel. It is worth less on an interface with a single consumer that ships in the same commit. The real question is not the order of the work but whether the contract ends up written down somewhere a machine can check.
What makes an API easy to use?
Predictability, more than any single convention. A caller who has used three of your endpoints should be able to guess the fourth, get the error they expect in the shape they expect, and page through a list the same way everywhere. Consistency is worth more than the individual choices it applies, which is why picking a convention and holding to it beats picking the best one.
Last reviewed by The Routebase Team.