API versioning is the practice of managing changes to an API over time while preserving compatibility for existing clients. Every API evolves — endpoints are added, request/response shapes change, behaviors shift — and versioning defines how those changes are communicated, negotiated, and enforced. Choosing the right strategy depends on your audience (public, partner, or internal), your release cadence, and how strictly you can coordinate client upgrades. The hidden insight most teams learn too late: the best versioning strategy is the one that minimizes the need to create new versions — achieved through additive-only changes, robust deprecation processes, and designing for forward compatibility from day one.
What This Cheat Sheet Covers
This topic spans 19 focused tables and 150 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
Table 1: Core Versioning Strategies
The four dominant API versioning strategies each sit on a different point of the visibility-complexity trade-off. URI path versioning wins on simplicity and cacheability but couples the version into the URL; header-based versioning is cleaner and increasingly preferred for internal/partner APIs in 2026 but is invisible in browser address bars. Choosing the wrong strategy for your audience creates migration friction that compounds with every release.
| Strategy | Example | Description |
|---|---|---|
GET /api/v1/users | • Version embedded in URL path. • Most widely used; excellent cacheability • Easy to route, proxy, and log • Does not follow REST purist principles (version is not a resource) | |
X-API-Version: 2 | • Version specified in a custom request header. • Keeps URLs clean; preferred for internal/partner APIs • Invisible in browser/logs without tooling • Rising adoption for microservice-to-microservice calls | |
GET /api/users?version=2 | • Version passed as a URL query parameter • Simple to test in a browser • harder to cache reliably • easily omitted by clients |