An API that never changes is rare — versioning strategy determines whether evolving it breaks every existing client or lets them upgrade on their own schedule.
# URL path versioning - explicit, easy to route, easy to see in logs GET /api/v1/users GET /api/v2/users # Header versioning - keeps URLs clean, less discoverable GET /api/users Accept: application/vnd.myapp.v2+json # Query parameter versioning - simple, but easy for clients to accidentally omit GET /api/users?version=2
The Real Question: How Long Do You Support Old Versions?
Versioning strategy matters less than the deprecation policy behind it — a clear, published timeline (e.g., “v1 supported for 12 months after v2 ships”) gives clients a genuine, actionable window to migrate, versus an ambiguous “we’ll turn it off eventually” that erodes trust and causes scrambling later.
A Reasonable Default
URL path versioning (/api/v1/...) remains the most widely adopted approach specifically because it’s the most discoverable — visible directly in logs, browser history, and documentation without needing to inspect request headers, which matters a lot for debugging and support conversations with API consumers.