What Is API Versioning?
API versioning is the practice of managing changes to an API over time so that existing clients don't break when the API evolves.
Published November 17, 2026
API versioning lets you change an API without breaking existing clients by publishing changes under a new version identifier, such as /v2/ in the URL or a version header.
The concept
Breaking changes (renamed fields, removed endpoints, changed behaviour) go into a new version while the old one keeps working for a deprecation period.
Common strategies: URL path (/v1/users), header (Accept: application/vnd.api.v2+json) and query parameter (?version=2). URL versioning is the most visible and simplest.
Two versions side by side
Practical examples
Laravel route groups
Route::prefix('v1')->group(fn () => Route::get('/users/{id}', [V1\UserController::class, 'show']));
Route::prefix('v2')->group(fn () => Route::get('/users/{id}', [V2\UserController::class, 'show']));Deprecation headers
Deprecation: true
Sunset: Wed, 01 Jul 2027 00:00:00 GMTNon-breaking changes need no new version
Adding optional fields or new endpoints is backward compatibleCommon mistakes
- Creating a new version for every small change.
- Removing old versions with no notice.
- Breaking changes inside an existing version.
Key takeaways
- New version for breaking changes only.
- URL versioning is simplest.
- Announce deprecations with dates.
FAQ
What counts as breaking?
Removing or renaming fields, changing types or semantics.
How long to support old versions?
Long enough for clients to migrate, often 6–12 months.