An API Versioning Interview Exercise With Two Active Clients

TL;DR

• In this fictional API exercise, two active clients cannot upgrade to a changed order-status contract together.
• Write both contracts explicitly and compare additive evolution with separate versions while keeping representations consistent.
• Use actual client evidence for deprecation, test mixed versions, and rehearse rollback.

Start with two clients that cannot upgrade together

Practice this fictional prompt: your API returns an order's status as a string. A new design needs a richer status object. A web client can deploy quickly, but an installed mobile client may remain on an older release. Explain how to evolve the API without silently breaking the mobile experience.

Do not begin by choosing a version number. First identify the contract change and the clients that depend on it. Replacing a string with an object can break a parser even if the endpoint path stays unchanged. Adding a new field may be compatible for some clients, but only if their parsing behavior allows it.

Write the old and proposed contracts explicitly

For the exercise, the old response contains status: "processing". The proposed representation includes a code, display label and timestamp. The domain may benefit from that structure, but existing clients do not automatically understand it.

Ask whether other consumers exist before declaring the inventory complete. Internal scripts and partner integrations can be easy to miss. The exercise should reveal how you discover compatibility obligations, not merely how you name an endpoint.

Compare additive evolution with explicit versioning

One candidate design keeps the old string and adds a separate structured field for newer clients. Another introduces an explicit API version with the changed representation. Explain the tradeoff: additive fields may reduce immediate disruption but create duplicated representations; a new version makes the contract boundary clearer but adds support and migration work.

GitHub's REST API version documentation provides a primary example of explicit API version selection. Treat it as one concrete design, not a rule that every service must copy its header or policy.

Whichever approach you choose, define behavior for an omitted or unsupported version. Do not allow a server deployment to silently reinterpret an existing client's request under a new contract unless that was already part of the agreed interface.

Keep the representations consistent

If both old and new fields are served, define one internal meaning and derive the response forms deliberately. Two independently updated fields can disagree. The old client might display processing while the new client displays completed, making the compatibility layer a source of inconsistent behavior.

List the states and map each to the old representation. If a new state cannot be represented faithfully in the old contract, acknowledge that limit. You may need a documented fallback, a restricted feature for older clients or a different migration plan. Do not assume a richer model can always be reduced without loss.

Our system design frameworks guide can help you make those requirements and tradeoffs visible. The key interview move is to expose the semantic incompatibility rather than hide it behind a serialization detail.

Plan deprecation from actual client evidence

A new version does not make the old one disappear. Define how you identify active consumers, communicate the change and decide whether retirement is safe. Client version or API-version telemetry can help, but it must be interpreted carefully: absence of recent traffic is not proof that an infrequently used client will never return.

For the fictional mobile app, consider what happens when a user opens an old installation after a long gap. Can it still perform essential actions, receive a clear upgrade message or use a limited compatibility path? State the product decision instead of assuming every user updates immediately.

Avoid inventing a universal support window. The appropriate period depends on the product, agreements and client lifecycle. In the interview, explain the inputs needed to choose a policy and how the service will enforce it predictably.

Consider generated clients as well. A schema change can alter generated types or validation even when a handwritten client would ignore the difference. Include the actual supported client artifacts in compatibility testing where possible. An API response that looks additive to a human may still violate a strict consumer’s assumptions.

Test mixed versions and rehearse a rollback

Build contract tests for both old and new clients against the same domain states. Include missing optional values, newly introduced states and error responses. A happy-path example for the newest web client is not enough to validate the compatibility plan.

Then ask what happens if the new web client rolls back while the API remains upgraded. If the server still supports the old contract, that may be straightforward. If the deployment removed the old response shape, rolling back only the client can make the incident worse. Deployment order belongs in the answer.

Use the mock interview strategy guide to retry the scenario with a request-field change rather than a response change. A strong answer identifies the consumers, preserves a clear contract, handles semantic differences and explains the evidence required before retiring compatibility support.