API Versioning

Also Known As

TL;DR

Explanation

URI versioning (/v1/, /v2/) is the most visible and cache-friendly approach. Header versioning (Accept: application/vnd.api+json;version=2) keeps URLs clean but is harder to test in a browser. Content negotiation uses the Accept header's MIME type. Semantic versioning applied to APIs: breaking changes require a major version bump. Deprecation policy: announce deprecation, support both versions for a transition period, then remove. Never silently change a response field — add new fields alongside old ones.

Common Misconception

Why It Matters

Common Mistakes

• Not versioning from day one — retrofitting versioning breaks all existing URL references.
• Deprecating a version without announcing a timeline and giving consumers adequate migration time.
• Using dates as version identifiers (2024-01-01) — hard to compare and communicate breaking vs non-breaking changes.

Avoid When

• Do not version internal APIs used by a single team — the overhead outweighs the benefit.
• Avoid creating a new version for every change — only major breaking changes warrant a new version.

When To Use

• Version your API from the first public release — never ship an unversioned public API.
• Use URI versioning for public APIs — it is explicit, cacheable, and easy to route.

Code Examples

// No versioning — any change breaks consumers
Route::get('/api/users', [UserController::class, 'index']);
// Removing a field or changing a response structure breaks all clients silently

// URI versioning — simple, explicit, cache-friendly
// routes/api.php
Route::prefix('v1')->group(function () {
    Route::get('/users', [V1\UserController::class, 'index']);
});
Route::prefix('v2')->group(function () {
    Route::get('/users', [V2\UserController::class, 'index']);
});

// Add deprecation header on old version
header('Deprecation: version="v1", sunset="2026-12-31"');

References

• ↗ https://restfulapi.net/versioning/

Tags

Related Terms