APIs
The design decisions behind interfaces.
What APIs covers
An API is the contract through which systems talk to each other. This category covers API design, versioning and the choice between REST, GraphQL and gRPC.
What this category covers
- REST vs. GraphQL vs. gRPC
- API versioning without breakage
- API design: idempotency, pagination, errors
- Building reliable webhooks
Solid answers in this field.
In-depth, citable documents — every recommendation with its trade-off, its cost and the case in which we decide differently.
Idempotency in Distributed Systems
Why distributed systems must tolerate duplicate messages and how to make them idempotent: idempotency keys, retries, outbox and inbox.
API Design for Long-Lived Systems
How to design APIs that last for years without breaking their consumers' systems: contracts, compatibility, versioning, errors, evolution.
REST, GraphQL or RPC — Choosing an API Style
Choosing an API style by fit rather than fashion: what distinguishes REST, GraphQL and RPC, which problem shape suits which style, what each one costs.
API Versioning Without Breaking Customers
How to evolve an API over years without breaking customers' systems: extend compatibly, version cleanly, treat deprecation as a process.
Lessons learned in this field.
Mistakes and what they taught us — anonymized, without drama. The mistake is the teacher.
New articles in this category are published on an ongoing basis. You can already find the core terms in the glossary.
Go to the glossaryContinue your engineering journey.
Related concepts, decisions, playbooks and perspectives — as one connected path, not a list of links.
Services
Concepts
Engineering decisions
Playbooks
A concrete problem in this field?
We don't just solve it on paper. Talk to the engineers who would build it.
