Prompt and scope
A company will retire its v1 API in 12 months and launch v2. v1 has 3,000 customers, about 40% of requests still use legacy fields, and 200 customers are high-revenue enterprises. Plan the migration while balancing new capability, compatibility, developer experience, revenue risk, and retirement.
This tests whether a product manager can turn a technical migration into a bounded customer product: identify who is affected, why the move matters, and which behaviors must not break; then design compatibility, tooling, communication, staged rollout, and exit criteria. GitHub’s API version guidance treats breaking changes, Deprecation/Sunset headers, support windows, and migration testing as version governance constraints.
What the interviewer is testing
First, can you segment customers and rank risk instead of announcing one date? High-revenue, regulated, low-activity, and self-service customers have different migration resistance.
Second, can you distinguish compatibility, migration, and retirement? Keeping an old version, adding an adapter, or providing batch conversion reduces risk but does not replace customer confirmation or an exit standard.
Third, can you move decisions with observable signals? Lower request volume does not prove migration; also track active applications, errors, field usage, completed migrations, and support burden.
Questions to clarify before answering
- What is v2’s core value? Security, performance, compliance, cost, or a new resource model?
- Which v1 behaviors break? List removed fields, type changes, authentication changes, and error semantics.
- Can customers see what they use? Is usage available by token, application, or organization?
- Is 12 months a hard deadline or a target? What evidence could trigger extension or staged closure?
- Can both versions or an adapter run together? What are the cost, latency, and consistency limits?
- What is the post-retirement support promise? How do 410 responses, docs, appeals, and security exceptions work?
A 30-second answer framework
“I would establish v1 usage baselines and customer segments, then list every breaking change and the benefit of v2. I would publish compatibility guidance, a diff inventory, validation tools, and an application-level usage dashboard, starting with high-value customers and internal integrations. During migration I would use docs, console notices, email, and direct outreach, plus Deprecation/Sunset headers and staged error drills. Each stage gets thresholds for adoption, errors, active-application migration, and support tickets; retire v1 only after exit criteria are met, with security exceptions and a short rollback window.”
Step-by-step deep dive
Step 1: Define goals and behaviors that must not break
Split goals into customer value and platform constraints. For example, v2 may provide finer-grained permissions while v1’s core read and write semantics remain stable during transition. List removed or renamed fields, new required parameters, type and enum changes, and authentication requirements. A 200 response alone does not prove compatibility.
Step 2: Establish usage baselines and risk tiers
Segment by organization, application, token, version, endpoint, field, request volume, revenue, compliance, and technical owner. Calculate each application’s 90-day activity, affected-field share, migration complexity, and customer value. A high-revenue low-volume customer still needs explicit confirmation; an application without an owner enters the risk queue early.
Step 3: Design migration paths and compatibility boundaries
Prefer additive migration: optional fields, parallel responses, or a v1-to-v2 adapter. For incompatible fields, provide equivalent mappings, example requests, and semantic differences. Give the adapter a deadline, cost, and observability; it must not permanently hide incomplete customer migration.
Step 4: Make tools and docs a product
Provide a diff list, application usage report, static checks or SDK migration hints, sandbox validation, sample code, and rollback instructions. Link every breaking change to replacement syntax and a test step. Tool output should be repeatable so customers do not have to guess from a long announcement.
inventory -> classify risk -> test v2 -> dual-run -> migrate -> verify -> retire v1Step 5: Stage rollout and communication
Start with internal and design partners, then self-service migration, then high-value or complex customers. Use changelogs, developer docs, console banners, email, and account-manager outreach at every stage. Put date, impact, action, support entry point, and exception terms in one migration contract so channels do not make conflicting promises.
Step 6: Gate on signals, not one adoption rate
Review v1 requests, active v1 applications, affected-field calls, v2 success rate, post-migration rollback rate, deprecation-header coverage, support tickets, and high-value customer confirmation weekly. Migration is complete only when the application switched, critical scenarios pass, errors are normal, and the owner confirmed it.
Step 7: Define retirement, extension, and exception rules
Before retirement, simulate a 410 or equivalent error in a test environment and verify that customers see an actionable guide. An extension needs evidence such as an unfinished security fix, a critical regulated customer still migrating, or a confirmed v2 regression. A security risk can justify earlier closure, but document impact, alternatives, and support. Every exception has an expiry date.
Step 8: Review the migration and institutionalize version governance
After retirement, inspect error peaks, retention, support cost, infrastructure savings, and unexpected usage. Preserve v1/v2 diffs, communications, decision logs, and incident timelines. Add support windows, breaking-change review, deprecation headers, migration tests, and customer notices to the next release template.
Trade-offs and boundaries
Trade-off 1: Adapter or fast switch
An adapter lowers short-term risk but adds maintenance, latency, and semantic ambiguity. Keep it only when migration value is clear, the boundary is observable, and an exit date exists; otherwise provide a clear v2 window instead of extending v1 indefinitely.
Trade-off 2: One deadline or customer waves
One date is easier to operate; waves control risk and give complex customers time. Keep a public final date while setting risk-based milestones and checkpoints so high-revenue customers do not surface problems in the last week.
Trade-off 3: Lower requests or real application migration
Requests can fall because of business decline, caching, or deactivation. Judge migration with active applications, successful critical endpoints, completed field replacement, and owner confirmation, not total traffic alone.
Failure drills and evolution plan
Drill 1: An omitted breaking field
Replay sampled real requests against v2 and compare status codes, error objects, pagination, timezones, and money semantics. Classify differences by severity; block wider traffic for any unexplained critical field.
Drill 2: A high-value customer is still on v1
Generate the customer list 90 days early and verify that account management, support, and product have owners. Offer one technical diagnosis and a time-limited exception instead of closing on the final day.
Drill 3: An error spike after retirement
Return 410 with a migration link in a small cohort or sandbox. Verify that SDKs, monitoring, and docs guide remediation. Set a short restore window with explicit triggers and record every activation.
Common mistakes and follow-ups
Mistake 1: Sending one deprecation email
Notification does not replace a usage inventory, code examples, test environment, or support entry point. Migration must be executable in the customer workflow.
Mistake 2: Treating the version number as all compatibility
Fields, errors, and authentication can change within a version. Maintain an itemized diff and contract tests.
Mistake 3: Keeping the old version forever
An adapter without an exit date splits docs, burdens infrastructure, and expands the security surface. Give every exception an owner and deadline.
Mistake 4: Ranking customers only by total requests
Low-volume applications can run critical accounting or compliance flows. Segment by value, impact, and technical complexity.
Mistake 5: Ignoring unversioned calls
Customers relying on a default version can see behavior changes after retirement. Identify requests without a version header and warn during transition.
Mistake 6: Not testing rollback or extension
A success-only rehearsal does not prove risk is controlled. Test error guidance, exception approval, restore windows, and extension criteria in advance.