Lesson 13 / 25

Versioning Strategies

Compare URI, header and media-type versioning strategies and plan deprecation with a clear migration window.

URI versioning

The most common approach in practice — visible, cacheable, and easy to route by, at the cost of duplicating a URI across versions.

GET /v1/orders/482
GET /v2/orders/482

Header-based versioning

Keeps the URI stable and treats a version as another content-negotiation axis — favored by API purists, but harder to test in a browser bar or curl by hand.

GET /orders/482 HTTP/1.1
Accept: application/vnd.example.v2+json

Whatever you pick, support overlap

Run at least two versions side by side with a published deprecation date for the old one — never flip a version overnight with no migration window.

Quick check: Which of these is a *breaking* API change that needs a new version?

Adding a new optional field to the response
Renaming an existing response field
Adding a new endpoint
Fixing a typo in documentation

Answer

Renaming an existing response field — Renaming or removing a field breaks any client reading the old name; additive changes like new fields or endpoints are typically safe.