Start here
If you're new to web APIs, start with How HTTP APIs Work — the missing layer of explanation between "I've used HTTP" and "I understand what's happening underneath." Then come back to this index when you have a specific question.
API styles
Three styles dominate web APIs in 2026. Each fits a different shape of problem.
- REST — the default for HTTP APIs. Resources, methods, status codes, caching, idempotency. Covers what to follow, what to skip, and the trade-offs behind each choice.
- GraphQL — for cases where REST forces too many round trips. Schema design, queries, mutations, the N+1 problem, and when GraphQL is the wrong choice.
- WebSockets — for bidirectional, low-latency push. Handshake, framing, authentication, scaling, reconnection, when to reach for them and when to use something simpler.
Cross-cutting concerns
Three problems that show up regardless of which API style you use:
- Authentication — API keys, OAuth 2.0, JWT, mutual TLS. What each is for, where each fails, and how to choose.
- Security — the broader picture: transport, authentication, authorization, input validation, rate limiting, secret management, incident response.
- SDK design — what makes a client library a pleasure to use, and what makes one a constant frustration.
Practical guides
Implementation-focused references for common tasks:
- Authentication in practice — secret storage, key rotation, session lifecycle, error handling, recovery from compromise.
- How to integrate with a web API — clients, retries, circuit breakers, observability, the patterns that distinguish robust integrations from fragile ones.
- Migrating between API versions and providers — strangler patterns, dual-write, traffic shifting, rollback.
Deep-dives on the blog
Long-form articles on specific subtopics that warrant more space than fits in a reference page:
- API Design Best Practices — the whole-system view of designing an API that ages well.
- Microservices Architecture Best Practices — the operational practices behind successful microservices.
- API Rate Limiting Strategies — token bucket, leaky bucket, fixed window, sliding window, with worked examples.
- Idempotency Keys for APIs — making retries safe for non-idempotent operations.
- Webhook Design and Delivery — signing, retries, ordering, replay protection.
- API Pagination Patterns — offset, cursor, keyset, and the failure modes of each.
- API Error Handling Conventions — status codes, problem-details envelopes, partial-success patterns.
How this is organised
The reference pages cover the protocol and design space — what REST is, what GraphQL is, what authentication options exist. The guide pages cover the implementation space — how to build with these tools in practice. The blog posts cover narrower subtopics in more depth than fits on a reference page.
If you're trying to decide between options, start with reference. If you have a decision and need to implement it, start with guides. If you have an implementation and want to know what could go wrong, start with the blog deep-dives.