API Versioning

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