Lesson 13 / 24

Versioning Strategies

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

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.

Where the version number lives: the URI, headers, or query string.

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
Adding a new endpoint
Renaming an existing response field

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.