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

GET /v1/users/7 → { "name": "Ada Lovelace" }
GET /v2/users/7 → { "first_name": "Ada", "last_name": "Lovelace" }

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 GMT

Non-breaking changes need no new version

Adding optional fields or new endpoints is backward compatible

Common 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.

More HTTP articles