Prompt and scope
The provider wants to remove /v1/items after a migration window, but clients are owned by different teams and some are dormant. Assume the provider can observe requests by client identity and can run /v2/items in parallel. The plan must distinguish a deprecation announcement from a removal date, preserve a safe fallback, and avoid claiming that a header alone migrates clients.
What the interviewer is testing
- Separating protocol signals, documentation, client inventory, and enforcement.
- Designing additive compatibility and a measurable migration gate.
- Handling unknown clients, long-lived integrations, and emergency rollback.
- Choosing status codes and headers without inventing semantics beyond the standards.
Clarifying questions to ask
Ask whether clients send a stable identity, whether /v2 can be additive, the minimum support period, contractual notice requirements, and whether the old endpoint can be read-only before removal. If identity is missing, migration evidence must come from credentials, network metadata, or explicit registration instead of guessed user agents.
The 30-second answer
I would inventory callers, publish a versioned migration guide, ship /v2 additively, and measure per-client traffic and error parity. Mark /v1 with the standardized Deprecation signal and a Sunset date, while exposing a dashboard and direct notices for known owners. Keep the old path during a stated window, enforce only after an evidence gate, and return a documented terminal response with a migration link. A feature flag and reversible routing provide rollback if a critical client breaks.
Step-by-step deep dive
1. Establish compatibility and evidence
Define field-level differences, default behavior, pagination, errors, and authentication changes. Run contract tests against both versions and compare representative responses. Tag metrics by client, version, endpoint, status, and migration state; do not use aggregate traffic alone because a low-volume client may be business-critical.
2. Signal deprecation precisely
The Deprecation response header communicates that a resource is deprecated; the Sunset header communicates a planned date after which it may become unavailable. They are signals, not a promise that every client understands them. Repeat the date in documentation and owner notifications, and include a stable migration reference in the response body or link relation defined by the API contract.
3. Migrate and enforce in stages
Start with warnings and dashboards, then require explicit exceptions for clients that miss the target. Offer shadow comparison or opt-in traffic before switching defaults. At the enforcement gate, reject only the old operation that is safe to retire, return a machine-readable error, and preserve a support path. Read-only compatibility can be extended longer than mutating compatibility when risk differs.
4. Keep rollback and governance real
Store the sunset date, owner, exception reason, and approval in a change record. Alert on post-migration error deltas and requests from unknown clients. Route the old path through a feature flag so rollback is a configuration change, not a code redeploy. After removal, retain telemetry and a tombstone response long enough to explain the failure without exposing secrets.
A strong sample answer
I would inventory 10,000 callers and define the exact /v1 to /v2 contract differences. Both versions run in parallel with per-client metrics and contract tests. /v1 responses carry Deprecation and Sunset signals, while documentation and owner notices repeat the date and migration steps. The provider moves through warning, opt-in, default-to-v2, and enforcement stages, with explicit exceptions and a machine-readable terminal error. A feature flag keeps rollback possible; the sunset gate is based on client-level evidence, not an aggregate traffic percentage.
Common mistakes
- Assume a header performs migration → many clients ignore it → pair standards signals with owner discovery and a guide.
- Set a date without an inventory → dormant but critical clients fail unexpectedly → require client identity and exception review.
- Compare only aggregate error rates → one tenant’s outage disappears in the average → monitor per-client parity and volume.
- Remove immediately after
/v2ships → clients have no proof of compatibility → run parallel or opt-in stages first. - Make rollback a redeploy → recovery is slow during an outage → route versions behind a reversible flag.
- Return an undocumented 404 at sunset → automation cannot distinguish removal from a typo → publish a stable terminal error and migration reference.
Follow-up questions and responses
A client never sends an identifying header. What is the migration gate?
Use the credential, account, network, or registration identity already available to the provider. If none is reliable, keep the endpoint available longer and require explicit registration before enforcement.
Can the Sunset date be moved?
Yes, if the change record, documentation, headers, and owner notices are updated together. Treat the date as a governance commitment and alert on clients that still depend on the old path.
What if /v2 is correct but slower for one client?
Compare the client’s latency and error budget separately, then optimize or grant a time-bound exception. Do not extend the entire population’s sunset window without evidence that the issue is systemic.
How do you retire a mutating endpoint safely?
Stop new writes after the evidence gate, preserve read access when possible, and make retries return a deterministic terminal error. Confirm downstream queues and audit records no longer depend on the old mutation before removal.