API styles
Three styles cover the vast majority of web APIs in 2026, each fitting a different shape of problem.
- REST — the default for HTTP APIs. Resource-oriented, cacheable, leans on the HTTP method semantics. Best for the broad case where clients are diverse and the request/response shape is straightforward.
- GraphQL — schema-driven, lets clients ask for exactly the fields they need in one round trip. Best for rich clients (single-page apps, mobile screens) where the alternative is a dozen REST calls.
- WebSockets — bidirectional, persistent connections for low-latency push. Best for chat, collaboration, live feeds — anywhere the server has updates the client needs immediately.
Adjacent: webhooks for server-to-server push (the API tells your server when something happens), and Server-Sent Events for one-way push from the server (lighter than WebSockets when you don't need bidirectional).
The HTTP layer underneath
Before the API style choice, there's the protocol it sits on top of. How HTTP APIs Work is the missing layer of explanation between "I've used HTTP" and "I understand what's actually happening." Methods, status codes, headers, the body, idempotency, caching. The shared substrate that REST and GraphQL and WebSockets all build on.
Authentication and authorization
Every API has to know who is calling, and what they're allowed to do.
- Authentication reference — API keys, OAuth 2.0, JWT, mutual TLS. The protocol-level reference: what each is for, where each fails, how to choose.
- Authentication in practice — secret storage, key rotation, session lifecycle, error handling, recovery from compromise. The implementation patterns that the reference doesn't cover.
Authorization — the harder problem of deciding what an authenticated caller can do — is covered in the security reference alongside the broader security model.
Security as a whole
Authentication is one layer; the security reference covers the rest: transport security, input validation, output handling, rate limiting, secret management, logging, and incident response. The goal is the layered model that production APIs actually need, not a checklist of OWASP entries.
Operational concerns
The patterns that distinguish a robust API from a fragile one usually live below the API style choice. The deep-dives:
- Rate limiting — token bucket, leaky bucket, fixed window, sliding window. The algorithm choice shapes burst tolerance and fairness.
- Idempotency keys — making non-idempotent operations safe to retry after a network failure.
- Webhook design and delivery — signing, retries, ordering, replay protection. What it takes to deliver events reliably to someone else's URL.
- Pagination — offset, cursor, keyset. The failure modes of each, and the API shape that exposes them well.
- Error handling — status codes, problem-details envelopes (RFC 7807), partial-success patterns. What separates an actionable error from a useless one.
Integrating with APIs
The flip side: when you're consuming an API rather than designing one.
- Integration patterns — clients, retries, circuit breakers, observability. The patterns that distinguish a robust integration from a fragile one.
- Migration patterns — strangler patterns, dual-write, traffic shifting, rollback. For when the API you depend on is changing or you're switching providers.
- SDK design — what makes a client library a pleasure to use. Useful both for SDK authors and for evaluating the SDKs you depend on.
Architecture and design
Two long-form pieces that pull together the design decisions across the whole API surface:
- API Design Best Practices — naming, versioning, error shapes, pagination, the small choices that compound into APIs that age well.
- Microservices Architecture Best Practices — the operational practices behind successful microservices, written for engineers who have to live with the architectural decisions.
What's not covered
For honesty: a few topics adjacent to APIs that this site doesn't cover well, by choice:
- Specific vendor APIs. We cover the general patterns; vendor-specific quirks belong in vendor docs.
- API gateways and service meshes. Brushed in passing, but a thorough treatment would need its own publication.
- gRPC. Important in some ecosystems, especially internal microservices, but mostly outside the HTTP/web-API focus of this site.
- Streaming systems. Kafka, Pulsar, event sourcing — adjacent to APIs but a different problem domain.
If we're missing something you wish we covered, let us know via the contact page.