You are designing a public payments API. Consumers are numerous, unknown and unmotivated to migrate. How do you handle breaking changes?

What the interviewer is testing

Whether you recognise that the versioning decision is about who bears the cost of change.

The two models

Push the cost to consumers. Version the API, deprecate old versions, require migration by a date. Cheaper for you, and it depends on consumers acting — which, for numerous unknown integrators with code they wrote years ago and are not going to revisit, they will not.

Absorb the cost centrally. Maintain compatibility so old integrations keep working indefinitely. Expensive for you, and it is the only model that works when a breaking change means your customers' payments stop.

For a public payments API, the second is close to mandatory.

The mechanism

Pin each account to the version it first integrated against. Requests are served according to that version unless the caller explicitly requests a newer one. Upgrading becomes an explicit action a consumer takes when ready.

Internally, maintain one current implementation with a chain of transformations mapping requests and responses to and from older versions. Adding a version means writing the transformation from its predecessor, so the burden is incremental rather than requiring parallel implementations.

This is Stripe's publicly-described approach and it is the most-cited answer to this problem.

The costs and constraints

A large number of live versions and their transformations to maintain and test.

Every change must be expressible as a transformation of the previous shape — a change that cannot be is one you cannot make this way, which constrains the design.

The internal model and external contract diverge, requiring discipline to keep the transformation layer thin rather than accumulating business logic.

What a strong answer adds

The best versioning strategy is one you rarely need. Additive evolution and tolerant readers avoid most breaking changes entirely, and a team versioning frequently usually has a modelling problem — the contract is exposing internal structure that keeps changing.

And publish the schedule machine-readably: Deprecation and Sunset headers exist for this and are underused, so consumers' own tooling can warn them.

Common weak answers

URI versioning with a two-year sunset, which assumes consumers will migrate. Never versioning, which means never fixing design mistakes.