How would you handle API versioning as a PM?

What interviewers test when they ask about API versioning, plus a strong answer with Stripe and Twilio specifics and the 2026 agentic angle.

API versioning: what it is and how to answer it in a PM interview

This question is not really about versioning schemes. It is about developer empathy, backward compatibility thinking, and whether you can lead a cross-functional decision rather than just recite a taxonomy.

What the interviewer is testing

Four things: (1) do you understand the difference between a breaking and an additive change? (2) can you define a deprecation process with specifics, not platitudes? (3) do you know how to instrument version adoption so engineering knows when it is safe to sunset? (4) do you have the judgment to say when to grandfather indefinitely versus force a migration? A candidate who lists the four versioning strategies but skips all of that is answering the engineering interview, not the PM interview.

Structure a strong answer

strong

"My job as PM here is not to pick the versioning scheme: engineering owns that implementation. My job is to make sure we never surprise a developer, we have a deprecation process that respects their roadmap, and we can instrument version adoption so we know when it is actually safe to sunset old versions.

On the technical side: the core choice is URI versioning (e.g., /v1/users) versus header versioning. URI is the default for most B2B API products because it is explicit, cacheable, works in a browser, and is easy to route in an API gateway. Header versioning keeps URLs clean but requires every developer to remember to set the header and makes curl debugging harder. For most platform products I would default to URI versioning unless there is a strong existing convention otherwise.

The most thoughtful implementation I have seen is Stripe's date-stamped pinning: each account is locked to the API version active at their first API call, and they can override it per-request via a Stripe-Version header. Stripe has shipped nearly 100 breaking changes under this model without forcing a single hard migration. The PM tradeoff is real maintenance cost for a long tail of versions, so it only works with tight internal encapsulation. Twilio takes a different approach: they publish end-of-life dates at least 12 months ahead and offer extended support for large enterprise clients who need more runway.

When I need to deprecate something, I set a minimum 12-month window, notify developers via changelog and direct email to anyone with active traffic on the old version (not just docs updates, actual usage-based outreach). I would add Deprecation and Sunset headers (RFC 8594) to every response on the old endpoint so clients see the signal in-band. And I would track version adoption weekly by client ID so I can tell engineering precisely when the tail is small enough to pull the plug.

The 2026 wrinkle: AI agents are now calling APIs with no human watching. If I have a tool schema that an autonomous workflow has hardcoded, a breaking change breaks that workflow silently. That raises the bar considerably. For any AI-facing API surface, I would treat schema changes the way mobile teams treat forced upgrades: assume the client will not self-update, additive-only by default, and much longer notice periods for anything structural."

weak

"There are four main types: URI versioning, query parameter versioning, header versioning, and content negotiation via the Accept header. URI versioning is the most common. You should use semantic versioning and give developers plenty of notice before deprecating." This lists a taxonomy and stops. It signals that you looked up the definitions but have not thought through the PM-specific levers: when to force migration versus grandfather, how to know which clients to contact, what constitutes an acceptable maintenance burden, or how to build the cross-functional process. The interviewer cannot distinguish you from someone who skimmed a Wikipedia article.

The PM judgment

The versioning decision maps directly to developer trust and retention, not just API design hygiene. A developer who gets surprised by a breaking change will route around your API if they can, or escalate to legal if they cannot. That is a churn event and a trust event, not a documentation problem.

The four strategies and their PM-relevant tradeoffs:

URI versioning (/v1/, /v2/): explicit, cacheable, easy to route, survives proxies and gateways. The cost is endpoint duplication as versions accumulate. GitHub uses this for its REST API (/v3/).
Header versioning: keeps URL space clean, signals technical sophistication. The cost is harder debugging, no browser testability, and developers who forget to set the header.
Query parameter versioning (?version=2): easy to implement, pollutes URLs, often cached incorrectly by CDNs.
Content negotiation (Accept: application/vnd.api+v2+json): the RESTful purist choice, highest implementation complexity, lowest adoption by clients.

GraphQL is a fifth path worth knowing: additive schema evolution means you rarely need a version bump at all. GitHub’s GraphQL API (/graphql, their v4) avoids most versioning entirely by extending schemas without removing fields.

The Stripe model as the benchmark

Stripe’s date-stamped versioning (e.g., 2024-09-30) is the most-cited gold standard for a reason. Every account is pinned at first API call. Developers who integrated years ago have never had a surprise. The model works because Stripe built internal abstraction layers that translate across versions server-side. The PM lesson: the maintenance cost of “version forever” is real, but if you encapsulate it internally, developers never pay it. That is a product and engineering investment worth making when your API is the product.

The 2026 shift: agentic consumers

AI agents and MCP tool-call interfaces have changed the stakes. When a human-coded integration breaks, a developer sees a 500, files a ticket, and patches it. When an autonomous agent’s tool schema breaks, the agent may fail silently, attempt wrong actions, or produce subtly incorrect outputs with no human in the loop to notice. The developer experience problem has become a reliability and trust problem at the product level.

OpenAI and Anthropic both address a related concern with model aliases: gpt-4o and claude-3-7-sonnet-20250219 let developers pin to capability and patch versions separately from the API schema. The versioning conversation in 2026 is converging on one idea across these companies: freeze the world for any given consumer until they explicitly opt in to change. As PM, your north star is zero-surprise integrations. That is now a retention metric, not just a developer relations nicety.