API Versioning

REST API versioning is the practice of managing changes to a RESTful API by creating different versions of the API. It helps maintain backward compatibility so existing clients continue to work even after updates or changes to the API.

Why API Versioning Is Important

• Allows adding new features without breaking old clients.
• Supports gradual migration for consumers.
• Maintains predictable API behavior.

If you deploy changes to request formats, response structures, authentication, or behavior, versioning provides a controlled way to introduce those changes.

Common API Versioning Strategies

Versioning Method	Example	Pros	Cons
URI Versioning	/v1/users	Simple, explicit in the URL	Can clutter URLs
Query Parameter Versioning	/users?version=1	Easy to add dynamically	Less visible, not RESTful
Header Versioning	Accept: application/vnd.myapi.v1+json	Clean URLs, flexible	Harder for clients to implement
Content Negotiation	Accept: application/json; version=1	Flexible, aligns with HTTP standards	Less common, more complex

Comparison

Feature	URI Versioning (/v1/users)	Header Versioning (Accept: v2)	Query Param Versioning (?version=2)
Clarity	✅ Very clear, explicit	❌ Hidden in headers	⚠️ Somewhat clear, but less prominent
REST purity	❌ Less RESTful (URI should be stable)	✅ More RESTful (representation in headers)	❌ Not ideal (query params aren’t for versioning)
Caching/CDN	✅ Excellent	⚠️ Needs config	⚠️ Sometimes problematic
Ease of adoption	✅ Easy for devs	⚠️ Requires header setup	✅ Easy to use, but messy
Migration	❌ Requires URL change	✅ Only header change	✅ Only param change
Best for	Public APIs (third-party devs)	Internal APIs (enterprise apps)	Experimental APIs, quick testing

API Versioning Lifecycle

1. 2023 → /v1 released

GET /v1/users/123 → { "id": 123, "name": "Alice" }

2. 2025 → /v2 released with breaking changes

GET /v2/users/123 → { "id": 123, "fullName": "Alice Johnson", "email": "alice@example.com" }

3. 2025 (Announcement) → Mark /v1 deprecated

• Docs updated with deprecation notice.
• Responses from /v1 include headers:

Deprecation: true
Sunset: Tue, 31 Dec 2026 23:59:59 GMT
Link: </v2/users/123>; rel="successor-version"

4. 2026 → /v1 fully retired.

• /v1/users/123 → returns 410 Gone.
• All clients must use /v2.