Versioning
Strategies for evolving an API without breaking existing clients
Overview
APIs change over time, but existing clients depend on the current behavior. Versioning lets you introduce breaking changes under a new version while old clients keep using the old one. The most common approaches are putting the version in the URL path or in a request header.
Syntax / Usage
URL versioning is the simplest and most visible: the version lives in the path. Header versioning keeps URLs clean by moving the version into a header.
# URL path versioning (most common for beginners)
GET /v1/users
GET /v2/users
# Header versioning
GET /users
Accept: application/vnd.example.v2+json
Examples
Version 1 returns a simple flat name field:
GET /v1/users/42
HTTP/1.1 200 OK
{ "id": 42, "name": "Ada Lovelace" }
Version 2 introduces a breaking change by splitting the name, without affecting v1 clients:
GET /v2/users/42
HTTP/1.1 200 OK
{ "id": 42, "firstName": "Ada", "lastName": "Lovelace" }
Common Mistakes
- Making breaking changes to an existing version instead of adding a new one
- Versioning everything for tiny additive changes (new optional fields don't break clients)
- Never deprecating old versions, leaving many to maintain forever
- Mixing versioning schemes across endpoints so clients can't rely on one
- Forgetting to document what actually changed between versions
See Also
api-design-rest-basics api-design-http-methods api-design-pagination