Semantic Versioning and Change Management

REST API versioning does not need to follow semver strictly, but the underlying principles apply: major versions for breaking changes, minor for additive changes, patch for bug fixes. Many public APIs expose only the major version number in the URL, since minor and patch releases are backward-compatible and existing clients continue to work. A changelog and deprecation notice policy ensures clients have time to migrate. The recommended timeline is to announce a deprecation in the documentation and via the Deprecation/Sunset headers, maintain both versions in parallel for at least 6 months, then retire the old version.

Example

# API versioning strategy table
# ┌─────────────────────────┬──────────┬────────────────────────────────────┐
# │ Change Type             │ Version  │ Example                            │
# ├─────────────────────────┼──────────┼────────────────────────────────────┤
# │ Remove field            │ MAJOR    │ v1 -> v2: remove /users/{id}/age   │
# │ Rename field            │ MAJOR    │ v1 -> v2: "name" -> "fullName"     │
# │ Change field type       │ MAJOR    │ v1 -> v2: price: string -> number  │
# │ Change status code      │ MAJOR    │ 200 -> 201 on POST                 │
# │ Add required field      │ MAJOR    │ new required field in request body │
# ├─────────────────────────┼──────────┼────────────────────────────────────┤
# │ Add optional field      │ MINOR    │ add optional "metadata" field      │
# │ Add new endpoint        │ MINOR    │ add GET /users/{id}/preferences    │
# │ Add new query param     │ MINOR    │ add ?include=tags support          │
# ├─────────────────────────┼──────────┼────────────────────────────────────┤
# │ Fix incorrect behaviour │ PATCH    │ fix pagination off-by-one error    │
# │ Performance improvement │ PATCH    │ no API contract change             │
# └─────────────────────────┴──────────┴────────────────────────────────────┘

# Deprecation timeline example
# Jan 2025: Announce v3, deprecate v2
# Jul 2025: Remove v2 (6-month window)
# Jan 2026: Remove v1 (12-month window, was deprecated Jul 2024)

# Date-based versioning (Stripe / AWS style)
GET /users/42 HTTP/1.1
API-Version: 2025-01-01
# Server pins the client to the API behaviour as of that date

HTML

Full Editor

Related Resources

REST API Reference

Complete tag & property list

REST API How-To Guides

Step-by-step practical guides

REST API Exercises

Practice what you've learned