Versioning an API

API design: REST, HTTP, GraphQL and gRPC Mid-level Python 3.13+ PostgreSQL 17+ Reviewed 31 Oct 2026 By Best Latest Apps

Pick the fix

You must change price from a number of euros to an object with amount and currency. Least disruptive approach?

OptionsAdd a new price_v2 object field, keep price as is, deprecate it with a dateChange price in place and tell clientsRemove price and add amount and currencyShip it as a minor version

Hint 1 of 1

Can old clients keep reading what they read today?

Choose an answer, then open Show answer below to check it.

Show answer

Answer: A Add a new price_v2 object field, keep price as is, deprecate it with a date

Correct. Additive change; old clients keep working until they move.

Old clients still read price as a number. Adding a new field and retiring the old one on a published date lets both kinds of client work during the move.

Why not the others?

B Change price in place and tell clients. Breaks every client that reads it as a number.
C Remove price and add amount and currency. Removing a field breaks old clients.
D Ship it as a minor version. The number on the version doesn't make a breaking change safe.

30-second answer

Prefer compatible changes so you rarely need a version: add optional fields and new endpoints, never remove or rename fields or change their meaning, and make clients ignore fields they don't know. When a breaking change is unavoidable, publish a new major version (in the path like /v2/, or by media type), run both in parallel, announce a deprecation date with Deprecation and Sunset headers, and track who still calls the old one.

Practise saying it · 35 s. No recording, just a timer

How do you version an API?

Say your answer out loud, then check which of these points you covered:

Compatible changes first
Never remove or rename
Tolerant readers
New major version for breaks
Deprecation and Sunset with data

Deep dive

Mobile apps make old versions live for years: users don't update.

Adding a value to an enum can break strict clients; document enums as extensible.

Making an optional request field required is breaking; making a required response field optional is too.

Contract tests and schema diffs in CI catch accidental breaks.

Common mistakes

Renaming a field 'because it's cleaner'.
Versioning every small change.
Shutting down v1 without usage data.

Senior take & follow-ups

Lead with compatible evolution, then the process for a real breaking change.

Follow-up questions

Think of your answer first, then open the hint.

Path or header versioning?
Show hint
Path is simplest to see and route; media-type versioning is cleaner but harder to use.
How do you know who's on v1?
Show hint
Log the version and client id per request.

Suggest a fix if something here is wrong or out of date.