Interview prompt
Problem context
Skills being evaluated
Use the sequence below to surface constraints, choose boundaries, test failure behavior, and defend trade-offs. Concrete numbers are interview assumptions, not claims about a real production system.
Clarify the decision
- Separate additive shape changes from semantic changes and identify clients with contractual support windows. Define what compatibility means for requests, responses, errors, ordering, defaults, and side effects.
Establish scale assumptions
- Measure traffic and revenue by API and SDK version, long-tail inactivity, webhook or callback dependencies, and support cost. Version decisions should use client evidence rather than age alone.
Functional and non-functional requirements
- Old clients remain safe during a published window, new clients can adopt capabilities incrementally, and incompatible behavior has a migration path. Operators must identify impacted customers before activation.
High-level architecture
- Use stable resource contracts, additive fields, explicit capability or version negotiation, generated conformance tests, and adapters around a canonical domain service. Major semantic forks receive separate endpoints or media versions.
Data model and flow
- Tag every request and response with resolved contract version and client identity. Normalize versions into canonical commands, then project version-specific responses so core business logic does not fork indefinitely.
Consistency and transaction boundaries
- Idempotency and side-effect semantics are part of the versioned contract. A validation tightening must not cause an old retry to create a new outcome.
Failure modes and recovery
- Unknown fields and capabilities degrade predictably, old versions have protected capacity, and rollback restores routing without losing canonical state. A version adapter failure is isolated from other cohorts.
Security and privacy
- Do not preserve vulnerable authentication or authorization behavior merely for compatibility. Security deprecations use accelerated notice, compensating controls, and explicit executive risk acceptance.
Observability and SLOs
- Track usage, errors, latency, deprecated behavior, and migration blockers by client and version. Provide customers with test environments and actionable compatibility reports.
Capacity and cost
- Every live major version adds code paths, tests, docs, and on-call load. Publish support tiers and remove versions only after usage, contractual, and incident risk are reviewed.
Alternatives and trade-offs
- Path versions are clear but encourage whole-API forks; capability negotiation reduces forks but complicates testing. Use additive evolution by default and major versions only for real semantic breaks.
Evolution and migration
- Announce, instrument, provide migration tooling, warn in-band, shadow the new semantics, enforce for opt-in cohorts, then sunset through a documented exception process. Remove adapters after traffic reaches zero and retention windows pass.
What Staff and Principal candidates should emphasize
- A strong answer versions behavior, not just JSON. It includes client identity, evidence-driven deprecation, security exceptions, canonical internals, and a credible path to delete compatibility code.
Decision trade-offs
Version mechanism
Option A
Major version in every endpoint path
Option B
Stable resources with additive capabilities
Recommendation:Prefer additive capabilities for compatible evolution; introduce a major contract only when semantics cannot be safely negotiated.
Sunset policy
Option A
Support every used version indefinitely
Option B
Published windows with reviewed exceptions
Recommendation:Use finite support windows and explicit paid or risk-approved exceptions so the long tail does not freeze security and product design.
Follow-up interview questions
- 01How do you tighten validation without breaking retries from old clients?
- 02When does an additive field become a semantic breaking change?
- 03How do you retire a version used by one high-revenue customer?
- 04Should SDK version and API contract version be coupled?
Common weak answers and mistakes
- 01Versioning URL shape while leaving error and side-effect semantics ambiguous.
- 02Assuming clients will notice release notes and upgrade on schedule.
- 03Forking business logic inside every version adapter.
- 04Keeping insecure legacy behavior under the banner of compatibility.
Interviewer evaluation rubric
Adds v2 endpoints but cannot define compatibility, client discovery, migration evidence, or removal.
Uses additive changes, explicit versions, telemetry, conformance tests, and a documented deprecation window.
Normalizes to canonical commands, versions semantics and idempotency, handles security, and supplies customer tooling.
Balances product velocity, enterprise contracts, and lifecycle cost through evidence-driven governance that actually deletes old paths.