API Design
Designing HTTP APIs that clients can understand, call safely, and keep using as the API changes.
HTTP for API Designers
The methods and status codes every API is built from, and what each promises a client.
HTTP methods for APIs: what GET, POST, PUT, PATCH and DELETE promise, and which are safe to repeat.
Beginner to Intermediate10 cards · 7 qnot started
HTTP status codes for APIs: choosing the code that tells a client what happened and what to do next.
Beginner to Intermediate9 cards · 7 qnot started
Designing the Contract
Shaping the resources, fields and errors a client sees.
REST and resource design: naming the things an API exposes and the paths that reach them, with filtering, sorting and actions that are not plain updates.
Beginner to Advanced11 cards · 7 qnot started
API contracts: the fields, types and formats a client and server agree on, written down so machines can check them.
Beginner to Advanced10 cards · 7 qnot started
API error responses: one error format a client can branch on, with enough detail to fix the request and nothing an attacker can use.
Beginner to Intermediate8 cards · 5 qnot started
Repeats, Retries and Long Jobs
Making responses reusable, writes safe to retry, and slow work answerable.
HTTP caching for APIs: telling clients and CDNs how long to keep a response, and using ETags to skip unchanged downloads and to stop two clients overwriting each other.
Beginner to Advanced11 cards · 8 qnot started
Idempotency keys: letting a client retry a payment or an order after a timeout without it happening twice.
Beginner to Advanced6 cards · 4 qnot started
Asynchronous APIs: answering a long job with 202 Accepted and a status to check, and sending signed webhooks a receiver can trust.
Beginner to Advanced9 cards · 5 qnot started
Securing an API
Knowing who is calling, what they may do, and how much they may ask for.
Authenticating API clients: API keys, sessions, bearer tokens, JWTs and mutual TLS, and which one suits each kind of caller.
Beginner to Advanced12 cards · 8 qnot started
OAuth 2.0 and OpenID Connect: letting an application act for a user without their password, and learning who that user is.
Beginner to Advanced11 cards · 7 qnot started
Protecting an API: the common API security risks, object-level checks, rate limits a client can act on, and what CORS does and does not do.
Beginner to Advanced10 cards · 8 qnot started
Evolving and Choosing a Design
Changing an API without breaking its clients, choosing a style, and designing one whole.
Versioning an API: telling breaking changes from safe ones, and retiring an old version without stranding its clients.
Beginner to Advanced9 cards · 6 qnot started
REST, GraphQL and gRPC: what each API style exposes, and how to choose one for an integration.
Beginner to Advanced9 cards · 5 qnot started
Designing an API end to end: from requirements to reviewed endpoints, errors and a contract for one feature.
Intermediate to Advanced7 cards · 6 qnot started