API Design

Intermediate · Roadmap · 21 lessons · 5 groups

How to design, secure, document, and operate an API as a product with its own contract — not the transport or infrastructure underneath it. Resource modeling, versioning, pagination, and error contracts; OAuth2/JWT/API-key authentication and the full authorization-model taxonomy in practice; OpenAPI documentation and a testing discipline built specifically for APIs (contract tests, mocking, load testing); the OWASP API Security Top 10; and the compliance standards an API has to answer to. Twenty-one lessons that assume computer-science (HTTP, TCP/IP, DNS) and system-design (REST/gRPC/GraphQL mechanics, rate limiting, caching, load balancing, gateways, event-driven messaging, microservices) as a starting point and go one layer up — the contract a client depends on, not the mechanics underneath it.

0%

Not started

Nothing saved yet. Progress is kept in this browser until you sign in.

Start the path

Designing the contract · 6

Real-time & integration patterns · 4

Authentication & authorization · 4

Documentation, testing & quality · 4

Security, performance & compliance · 3

01REST Resource Modeling and URI DesignHow to think in resources instead of actions, and the concrete rules that turn that thinking into clean, predictable URIs.Beginner · 13 min02API Versioning StrategiesHow to signal API versions to clients, what actually counts as a breaking change, and how to retire an old version without an outage.Intermediate · 7 min03Pagination, Filtering, and SortingOffset versus cursor pagination and why cursors win at scale, plus the query-parameter and response-envelope conventions that make large collections usable.Intermediate · 26 min04HATEOAS and the Richardson Maturity ModelREST's actual hypermedia ideal, why almost no production API reaches it, and SOAP as the contract-first alternative that still survives in enterprise.Intermediate · 19 min05CORS and Content NegotiationPreflight mechanics and the Access-Control headers that make cross-origin requests work, plus how the Accept header negotiates response shape and version.Intermediate · 13 min06Structured Error Handling and RFC 7807The Problem Details JSON shape for HTTP API errors, and how to design a consistent, machine-readable error contract instead of ad hoc error bodies.Intermediate · 16 min01Streaming and Real-Time API ContractsExposing real-time data as a documented API surface — choosing between SSE, WebSockets, and long-polling, and designing an event schema clients can build to.Intermediate · 10 min02Webhooks vs. PollingDesigning webhook delivery a receiver can trust — retry/backoff, HMAC signing, idempotent receipt against at-least-once delivery — and when polling wins.Intermediate · 23 min03Synchronous vs. Asynchronous API DesignWhen to make a client wait for a result versus accept it and let them check back later — the 202 Accepted plus status-polling pattern, and when to notify.Intermediate · 9 min04Batch Processing APIsDesigning bulk endpoints that accept many items in one request — request/response shape, partial-failure semantics, and when a batch becomes its own async job.Intermediate · 46 min01OAuth2 and OIDC in PracticeWiring OAuth2 into an API you build — which grant type fits which client, how access and refresh tokens rotate, and how OpenID Connect layers identity on top.Advanced · 33 min02JWT, API Keys, and Session AuthFour ways to authenticate a request — JWT structure and the mistakes that break it, API keys, Basic Auth, session cookies — and which fits which consumer.Intermediate · 13 min03Authorization Models: RBAC, ABAC, and BeyondThe authorization-model taxonomy — RBAC, ABAC, PBAC, ReBAC, MAC, DAC — and the signals that tell you which one fits the access-control problem in front of you.Advanced · 19 min04API Key Management and ScopesHow to issue, store, scope, rotate, and revoke API keys safely, and why keys matter as a rate-limiting identity even for callers who barely need authentication.Intermediate · 19 min01OpenAPI and the API Documentation Tooling LandscapeWhat an OpenAPI document describes, the tradeoff between writing the spec first and generating it from code, and the categories of tool that sit on top of it.Beginner · 44 min02Contract Testing for APIsConsumer-driven contract testing against the OpenAPI spec — catching a breaking API change before either side of the boundary relies on it.Intermediate · 10 min03Mocking and Virtualizing APIsGenerating a mock server from an OpenAPI spec and virtualizing third-party dependencies, so frontend progress and test reliability don't wait on a real backend.Intermediate · 18 min04Load Testing APIsLoad testing an API specifically — a realistic traffic pattern, the real difference between load, stress, spike, and soak tests, and what to assert against.Intermediate · 14 min01The OWASP API Security Top 10The ten most common ways a real API gets broken into, led by broken object level authorization — a narrower list than the general web-application OWASP Top 10.Advanced · 30 min02API Performance Metrics and MonitoringWhat to actually watch about an API's own contract in production — latency percentiles, per-endpoint error rate, throughput, and usage analytics.Intermediate · 13 min03Data Privacy and Compliance Standards for APIsHow GDPR, CCPA, PCI-DSS, and HIPAA translate into API design decisions — minimal payloads, consent and erasure endpoints, audit logging, and tokenization.Intermediate · 21 min

Designing the contract

6 lessons

  1. 01 / 06REST Resource Modeling and URI DesignHow to think in resources instead of actions, and the concrete rules that turn that thinking into clean, predictable URIs.13 min
  2. 02 / 06API Versioning StrategiesHow to signal API versions to clients, what actually counts as a breaking change, and how to retire an old version without an outage.7 min
  3. 03 / 06Pagination, Filtering, and SortingOffset versus cursor pagination and why cursors win at scale, plus the query-parameter and response-envelope conventions that make large collections usable.26 min
  4. 04 / 06HATEOAS and the Richardson Maturity ModelREST's actual hypermedia ideal, why almost no production API reaches it, and SOAP as the contract-first alternative that still survives in enterprise.19 min
  5. 05 / 06CORS and Content NegotiationPreflight mechanics and the Access-Control headers that make cross-origin requests work, plus how the Accept header negotiates response shape and version.13 min
  6. 06 / 06Structured Error Handling and RFC 7807The Problem Details JSON shape for HTTP API errors, and how to design a consistent, machine-readable error contract instead of ad hoc error bodies.16 min

Real-time & integration patterns

4 lessons

  1. 01 / 04Streaming and Real-Time API ContractsExposing real-time data as a documented API surface — choosing between SSE, WebSockets, and long-polling, and designing an event schema clients can build to.10 min
  2. 02 / 04Webhooks vs. PollingDesigning webhook delivery a receiver can trust — retry/backoff, HMAC signing, idempotent receipt against at-least-once delivery — and when polling wins.23 min
  3. 03 / 04Synchronous vs. Asynchronous API DesignWhen to make a client wait for a result versus accept it and let them check back later — the 202 Accepted plus status-polling pattern, and when to notify.9 min
  4. 04 / 04Batch Processing APIsDesigning bulk endpoints that accept many items in one request — request/response shape, partial-failure semantics, and when a batch becomes its own async job.46 min

Authentication & authorization

4 lessons

  1. 01 / 04OAuth2 and OIDC in PracticeWiring OAuth2 into an API you build — which grant type fits which client, how access and refresh tokens rotate, and how OpenID Connect layers identity on top.33 min
  2. 02 / 04JWT, API Keys, and Session AuthFour ways to authenticate a request — JWT structure and the mistakes that break it, API keys, Basic Auth, session cookies — and which fits which consumer.13 min
  3. 03 / 04Authorization Models: RBAC, ABAC, and BeyondThe authorization-model taxonomy — RBAC, ABAC, PBAC, ReBAC, MAC, DAC — and the signals that tell you which one fits the access-control problem in front of you.19 min
  4. 04 / 04API Key Management and ScopesHow to issue, store, scope, rotate, and revoke API keys safely, and why keys matter as a rate-limiting identity even for callers who barely need authentication.19 min

Documentation, testing & quality

4 lessons

  1. 01 / 04OpenAPI and the API Documentation Tooling LandscapeWhat an OpenAPI document describes, the tradeoff between writing the spec first and generating it from code, and the categories of tool that sit on top of it.44 min
  2. 02 / 04Contract Testing for APIsConsumer-driven contract testing against the OpenAPI spec — catching a breaking API change before either side of the boundary relies on it.10 min
  3. 03 / 04Mocking and Virtualizing APIsGenerating a mock server from an OpenAPI spec and virtualizing third-party dependencies, so frontend progress and test reliability don't wait on a real backend.18 min
  4. 04 / 04Load Testing APIsLoad testing an API specifically — a realistic traffic pattern, the real difference between load, stress, spike, and soak tests, and what to assert against.14 min

Security, performance & compliance

3 lessons

  1. 01 / 03The OWASP API Security Top 10The ten most common ways a real API gets broken into, led by broken object level authorization — a narrower list than the general web-application OWASP Top 10.30 min
  2. 02 / 03API Performance Metrics and MonitoringWhat to actually watch about an API's own contract in production — latency percentiles, per-endpoint error rate, throughput, and usage analytics.13 min
  3. 03 / 03Data Privacy and Compliance Standards for APIsHow GDPR, CCPA, PCI-DSS, and HIPAA translate into API design decisions — minimal payloads, consent and erasure endpoints, audit logging, and tokenization.21 min
Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark