API Design
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.
Designing the contract
- REST Resource Modeling and URI DesignHow to think in resources instead of actions, and the concrete rules that turn that thinking into clean, predictable URIs.
- API 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.
- Pagination, 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.
- HATEOAS 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.
- CORS 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.
- Structured 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.
Real-time & integration patterns
- Streaming 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.
- Webhooks vs. PollingDesigning webhook delivery a receiver can trust — retry/backoff, HMAC signing, idempotent receipt against at-least-once delivery — and when polling wins.
- Synchronous 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.
- Batch 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.
Authentication & authorization
- OAuth2 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.
- JWT, 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.
- Authorization 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.
- API 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.
Documentation, testing & quality
- OpenAPI 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.
- Contract Testing for APIsConsumer-driven contract testing against the OpenAPI spec — catching a breaking API change before either side of the boundary relies on it.
- Mocking 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.
- Load 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.
Security, performance & compliance
- The 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.
- API 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.
- Data 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.