🌏 中文版
Today's Focus
One of the clearest tells of depth in a Technical PM interview is the question "how would you version this API?" Most candidates jump straight to an answer — "we'd use path versioning, v1 and v2" — but that only answers how you'd label a version. It skips the actually hard part: who absorbs the upgrade cost (does the platform team eat the compatibility burden, or does every customer have to migrate), how often a breaking change is allowed, and — once sales has signed a contract promising "no unannounced format changes" — how the engineering team's day-to-day release rhythm has to line up with that promise.
This topic matters in interviews because it tests whether you can translate what looks like a surface-level technical spec choice into a business decision with a clear owner for the cost — instead of dropping a technical-sounding term and calling it done.
Framework Cheat Sheet
Comparing API Versioning Strategies
Before deciding how to version, lay out the trade-offs of the common options instead of picking one on instinct:
| Strategy | How it works | Impact on customers | Engineering maintenance cost |
|---|---|---|---|
Path versioning (/v1/, /v2/) | Major version is marked directly in the URL | Clear, but every major change forces customers to actively migrate to the new path | Medium — multiple code paths have to be maintained in parallel |
| Header versioning | Customer specifies a version number in the request header | Easy to miss which version you're actually on, so upgrade notices get passively ignored | Low — logic can share the same routing |
| Date-based rolling versions | Every change is tagged with a release date; accounts can pin to a specific date's version | Most granular — customers decide their own upgrade cadence | High — every historical date's behavior snapshot has to be maintained |
How to use it in an interview: when asked "how would you version this API," don't just answer the format. Say whose shoulders the upgrade cost lands on with your choice, and how that maps to what the company cares about most right now — customer trust versus engineering maintenance capacity.
The Cost-Reversibility Trade-off Matrix
Technical decisions often get flattened into "this option is more expensive / cheaper," but the axis that actually matters is two-dimensional: short-term implementation cost, and whether the decision can be undone later.
| Easy to reverse | Hard to reverse | |
|---|---|---|
| Low short-term cost | Just do it, validate fast (e.g. run one version manually first and watch for real demand) | The danger zone — cheap now, but it locks in future options, so treat it carefully |
| High short-term cost | Can wait until the signal is clearer before investing | Needs RFC/ADR-level scrutiny, usually requiring cross-team alignment first |
How to use it in an interview: when asked "how do you decide whether a more robust engineering solution is worth the extra investment," don't just cite ROI. First place the decision on this matrix — and call out anything in the "hard to reverse" quadrant explicitly, because that's where risk gets underestimated most often.
Today's Practice Question
The Question
"You just joined a mid-size SaaS company as the platform team's Technical PM. Sales closed a major enterprise contract requiring API access to three core data objects — billing, usage, and audit logs — within six months. The contract also states the API format cannot change without notice, or the customer can claim a penalty. You look at the current state and find the engineering team's practice is to change existing REST response fields directly whenever a requirement shifts, with no versioning strategy at all. How would you design a plan for this, and how would you get engineering to accept the new constraint?"
(Source: original, scenario designed around API-first product and architecture trade-off question types common in Dataford's Docusign and Fivetran Technical PM interview guides)
How to Break It Down
- Clarify the question first: what exactly does "no unannounced format changes" mean in the contract — how much notice counts as "announced," and does a format change include adding new fields, or only removing fields or changing types? How many existing customers are already using these three objects, and how fragile are their current integrations? Beyond this one enterprise customer, what other internal needs over the next six months would push engineering toward changing the format?
- Define the users: there are at least two groups to serve here at once — the enterprise customer's integration engineers (who care about stability and don't want to rewrite integration code every quarter) and the internal engineering team (who care about being able to keep iterating on the data structure without being locked in by a past promise). The plan can't favor just one side.
- Structure the analysis: use the versioning strategy comparison table to rule out path versioning (too coarse for a customer that needs fine-grained control over their own upgrade cadence) and header versioning (too easy to ignore, can't give a clear compatibility guarantee) — leaving date-based rolling versions as the candidate. Then run it through the cost-reversibility matrix: introducing a versioning system now falls into the "high short-term cost, hard to reverse" quadrant, meaning this deserves an RFC before engineering decides on its own.
- Propose a fix: adopt date-based rolling versions — monthly releases only allow backward-compatible changes (new optional fields, no removed or retyped fields), while a twice-a-year major release is the only place breaking changes are allowed, announced in advance via documentation and a changelog. Every customer account defaults to pinning the version active when they first integrated, unless they opt to upgrade. Translate the contract's promise into an internal rule: any change that needs to skip this process goes through an exception review, rather than being allowed by default.
- Define success: the guardrail metric is the number of support tickets or complaints generated by each monthly release, which should stay low. The primary metric is zero unexpected-format-change complaints from the enterprise customer over the six-month period. Also track the extra engineering hours spent maintaining multiple versions as a share of total capacity — if that crosses a threshold, it's a signal the versioning granularity needs renegotiating rather than letting a stability promise eat engineering capacity indefinitely.
Sample Answer (How You'd Actually Say This in an Interview)
Clarifying and framing the problem: "First I'd confirm what 'no unannounced format changes' actually means in the contract — does it mean these three objects can't change at all, or just that breaking changes need advance notice while additive changes like new fields are fine? That distinction decides how strict a versioning system I need to design. I'd also check how many existing customers are already using these APIs, since they'll be affected by the transition to a new system too."
Structured analysis and proposal: "Once that's clear, I'd rule out path versioning and header versioning — the first is too coarse for a customer that needs fine-grained control over its own upgrade timing, and the second is too easy to ignore and doesn't give a clear compatibility guarantee. I'd go with date-based rolling versions, following a pattern the industry has already validated — monthly releases only ship backward-compatible changes, and only a twice-a-year major release is allowed to touch existing fields, with every account defaulting to the version active when it first integrated. Because introducing this system is a high-cost, hard-to-reverse decision, I wouldn't let engineering decide this on their own. I'd write a short RFC first that translates this promise into internal rules — for example, what counts as an exception, and who has authority to approve skipping the process for an urgent change."
Defining success: "I'd check whether this plan actually works with two sets of metrics. The guardrail is that support tickets or complaints shouldn't rise after each monthly release. The primary metric is zero unexpected-format-change complaints from this enterprise customer over the six-month contract period. But I'd also track the share of engineering time spent maintaining backward compatibility across versions — if that cost gets high enough to eat into normal development capacity, that's a signal the versioning granularity needs renegotiating, rather than letting one business promise hold engineering resources hostage indefinitely."
Self-Check List
Use this table to check whether your answer covered the key points:
| Check item | Covered? |
|---|---|
| Clarified the exact boundary of the contract promise instead of assuming "nothing can ever change" | |
| Served both external customer stability and internal engineering velocity as users, not just one side | |
| Compared versioning strategy options structurally instead of picking one from experience alone | |
| Assessed the reversibility of the decision to decide whether it needed an RFC-level review first | |
| Success metrics covered both customer protection and an engineering cost ceiling, not just one side | |
| Bonus: cited a real product case backing up the long-term viability of the versioning strategy |
Today's Case
Stripe: date-named rolling versions that have kept its public API from ever truly breaking
Stripe's public API versioning strategy uses rolling versions named by their release date (for example, 2017-05-24). Every account gets pinned to the latest version at the moment of its first API call, and nothing changes afterward unless the developer actively opts in to upgrade via the dashboard or a request header. Stripe's rule is that routine monthly updates only contain backward-compatible changes — new fields, fixes to clearly-broken behavior — while twice a year, a named major release (for example 2024-09-30.acacia) is the only place a genuinely breaking change is allowed, fully documented in advance in the official changelog. This mechanism lets Stripe keep improving its API while holding a public promise that "your integration won't break without warning."
How to use it in an interview: this is the real-world answer to the "six-month contract demands no unannounced API format changes" scenario question above. Use it directly when asked to "name an API versioning strategy you think is well done," or to check whether your own answer missed a key detail — specifically, "pinning accounts to a version" and "splitting the cadence of major versus minor releases" are exactly the kind of careful design the "hard to reverse" quadrant of the cost-reversibility matrix calls for.
Further Reading
- APIs as infrastructure: future-proofing Stripe with versioning — Stripe's official blog post explaining the design rationale and trade-offs behind its date-based rolling version strategy
- Docusign Product Manager Interview Questions & Guide 2026 — a real Technical PM interview question bank, including "how do you evaluate architectural trade-offs with engineering" and "how would you scope an API-first product for enterprise signing workflows"
- Fivetran Product Manager Interview Questions & Guide 2026 — Technical PM interview prep for data-platform roles, emphasizing API design principles and data-architecture communication skills
References
- APIs as infrastructure: future-proofing Stripe with versioning — source for the versioning strategy comparison in "Framework Cheat Sheet" and the full mechanism described in "Today's Case"
- Docusign Product Manager Interview Questions & Guide 2026 — source for the API-first product scoping and architecture trade-off question design in "Today's Practice Question"
- Fivetran Product Manager Interview Questions & Guide 2026 — source for the technical trade-off communication emphasis in "Today's Focus"
Loading...