API Versioning Strategies Backward Compatibility

API versioning is one of the most consequential decisions a backend team makes, and interviewers use it to probe whether a candidate thinks about long-term system evolution or just short-term feature delivery. This article covers the major versioning strategies, the backward-compatibility rules that actually hold up in production, and how to answer this question when it appears in a system design or API design interview round in 2026.

Why This Question Comes Up So Often

Every API with external consumers eventually needs to change its contract. The question interviewers ask — directly or embedded in a broader system design prompt — is: how do you evolve an API without breaking existing clients? This tests whether you understand that a breaking change isn’t just a technical event, it’s a coordination problem across teams and external partners who may not upgrade for months or years.

The Four Major Versioning Strategies

URI versioning (/v1/orders, /v2/orders) is the most common in practice because it’s explicit, cacheable, and easy to route at the gateway/load-balancer layer. Its downside: it encourages entire-endpoint duplication rather than granular evolution, and URLs are supposed to represent resources, not versions, per strict REST purism.

Header versioning (Accept: application/vnd.company.v2+json or a custom Api-Version header) keeps URLs clean and is favored by API-first companies like Stripe and GitHub. The tradeoff is discoverability — versions aren’t visible in the URL, so debugging and documentation require more discipline, and caching proxies need to vary on the header.

Query parameter versioning (?version=2) is the least recommended for production APIs; it’s easy to implement but doesn’t compose well with caching layers and is often seen as a smell in senior-level reviews.

No explicit versioning, backward-compatible-only evolution — the approach Stripe famously uses via dated version strings (2026-06-15) tied to each API key, letting each customer pin to the version active when they integrated, while the backend maintains transformation layers between versions internally. This is the most operationally sophisticated pattern and is worth mentioning to signal advanced knowledge.

Comparison Table

Backward Compatibility Rules That Actually Matter

The rules interviewers expect you to state explicitly, because they generalize across REST, GraphQL, and gRPC:

1. Never remove a field consumers may depend on; deprecate it, document the removal date, and monitor usage before removal.
2. Only add optional fields, never required ones, to existing response schemas.
3. Never change a field’s type or semantic meaning in place — introduce a new field name instead (amount stays an integer in cents forever; don’t silently switch it to a float dollar value).
4. Additive enum values are a breaking change for strict clients — a client with an exhaustive switch statement on an enum will crash or misbehave on an unrecognized new value. This is a favorite gotcha in interviews: many candidates assume “adding an enum value” is always safe.
5. Version your event schemas the same way as your APIs if you emit Kafka/webhook events — this is the part most candidates forget.

gRPC and Protobuf-Specific Considerations

If the interview touches gRPC, mention Protobuf’s field-number-based wire format: fields identified by number, not name, meaning renaming a field is safe but reusing an old field number is catastrophic (silent data corruption). Deprecated fields should be marked reserved to prevent accidental reuse — this is a specific, testable piece of knowledge that separates candidates who’ve shipped gRPC services from those who haven’t.

Deprecation and Sunset Communication

A mature answer includes the operational side: emitting a Deprecation and Sunset HTTP header (per RFC 8594) on old-version responses, tracking per-client version usage via API-key-tagged metrics, and running a staged sunset (warn at 90 days, throttle at 30 days, cut off after) rather than a hard cutoff. This shows the interviewer you think about the human/organizational side of the API lifecycle, not just the schema mechanics.

FAQ

Q: Is URI versioning considered an anti-pattern at senior level? A: Not an anti-pattern, but interviewers expect you to know its tradeoffs versus header-based or dated versioning. URI versioning is a pragmatic, easy-to-operate choice; the “more sophisticated” answer references Stripe’s dated-version model when asked to go deeper.

Q: What’s the biggest backward-compatibility mistake candidates miss? A: Treating enum additions as automatically safe. A client with an exhaustive switch/case on an enum can break when the server starts returning a new, previously unseen value. State this explicitly to stand out.

Q: How do you version internal microservice APIs differently from public APIs? A: Internal APIs can lean more on coordinated deploys and contract testing (e.g., Pact) since you control both sides, allowing faster iteration without external version pinning. Public APIs need much longer support windows because you don’t control consumer upgrade cadence.

For a full walkthrough of API design interview questions, including versioning, pagination, and idempotency-key patterns, see The 0-to-1 SWE Interview Playbook: https://www.amazon.com/dp/B0H256Z1MF?tag=sirjohnnymai-20.