API design
API versioning: interview questions and practical design
API versioning is a compatibility strategy for changing a contract while existing clients continue to function against the guarantees they adopted.
Written and reviewed by Sahil Srivastav
What it actually is
API versioning is a compatibility strategy for changing a contract while existing clients continue to function against the guarantees they adopted.
A breaking field rename or semantic change can fail clients that cannot deploy at the same time as the server.
The useful interview answer is precise about the boundary: Prefer additive changes, tolerant readers, and server defaults where semantics stay clear. A new version is justified when old and new clients require incompatible meaning or validation.
Why it matters in production
A breaking field rename or semantic change can fail clients that cannot deploy at the same time as the server.
Versioning has a cost: every supported contract adds tests, documentation, observability, and a retirement obligation.
How it works
Compatibility before versions
Prefer additive changes, tolerant readers, and server defaults where semantics stay clear. A new version is justified when old and new clients require incompatible meaning or validation.
Location of the version
A path, header, or media type can carry the version. Choose one convention, make routing and metrics explicit, and avoid a version that is invisible to logs and support tooling.
Migration and retirement
Publish deprecation dates, measure usage by version, provide a migration path, and remove the old contract only after owners have moved or accepted the risk.
Implementing it
Design an additive response change and a breaking validation change for one endpoint.
Run old and new clients against a compatibility fixture during a rolling deploy.
Add version-labelled metrics so a sunset decision is evidence-based.
Interview questions and how to answer them
When should an API get a new version?
When existing consumers cannot interpret the new contract safely and compatibility techniques cannot preserve the old meaning. A cosmetic or additive change usually does not need one.
Path or header versioning?
Either can work. Path versions are visible and cache-friendly; headers keep resource URLs stable but require stronger tooling and observability. Choose based on clients and operational needs.
How do you deprecate a version?
Announce a date, expose migration examples, measure calls by consumer, contact owners, and reject only after the supported window and rollback plan are real.
Answers that lose the round
- Creating v2 for every new optional field.
- Keeping versions forever without usage measurement or ownership.
- Versioning URLs while leaving event schemas and SDKs undocumented.
- Changing a field’s meaning under the same version.
FAQ
Is versioning a substitute for backward compatibility?
No. A new version still needs a migration and old clients still need a stable contract during the transition.
Should database schemas be versioned like APIs?
They need compatible rollout discipline, but storage migration and client API versioning solve different ownership problems.
What about event versions?
Treat schemas as public contracts: use explicit event versions or compatible evolution and make consumers tolerate redelivery and unknown fields.