API Versioning: Strategies That Do Not Break Your Clients
Breaking changes without versioning burn trust. URI, header, or parameter? Contracts, deprecations, communication.
Topic guide
Designing robust APIs: REST principles, GraphQL trade-offs, versioning, authentication, webhooks, and idempotency in real integrations.
3 topics · 11 articles
Resources, HTTP verbs, status codes, and versioning.
Breaking changes without versioning burn trust. URI, header, or parameter? Contracts, deprecations, communication.
Most APIs handle errors inconsistently. A well-defined pattern reduces integration bugs and makes debugging easier.
Authorization code with PKCE replaced the implicit flow. The full flow, ID token validation, and the BFF pattern for SPAs without tokens in localStorage.
A 15-minute access token, a refresh token in an HttpOnly cookie, a revocation list in Redis, and claim validation on every request. The full Node flow, from login to logout.
Trade-offs and when to use each.
GraphQL kills over-fetching and adds its own complexity. Where it beats REST today and where it became dead weight.
Tokens, webhooks, and calls that can be safely retried.
OAuth 2.0 is a protocol; JWT is a token format. What RFCs 7519, 8725 and 9700 say about validation, revocation and what OAuth requires today, such as PKCE and an exact redirect URI.
Internal networks earn no default trust. mTLS, service JWTs, and workload identity in real environments.
The committed .env remains software's most common leak. Vaults, rotation, and safe credential injection.
Webhooks fail quietly: duplicates, out-of-order events, silent losses. Complete checklist for receiving events without losing any.
Injection and broken access control lead the OWASP Top 10. The two-user test, CSP, Argon2, and the checklist that closes one real risk per CI run.
Token bucket, fixed window, and sliding log solve different problems. Key by IP, user, or API key, headers the client reads, and per-route limits. Code with Redis and express-rate-limit.
REST is simpler and benefits from HTTP caching; GraphQL is flexible but more complex to run. For most cases, start with REST.
For small teams, usually yes. It pays off when many clients with different data needs consume the same API.
Versioning in the URL (/v1/, /v2/) is the clearest for consumers. Header versioning is an alternative when you want stable URLs.
For internal service-to-service communication, where performance and typed contracts matter. For public APIs, prefer REST: gRPC requires HTTP/2 and binary payloads.