Design an API versioning strategy
PremiumAPI designEasy
- API versioning
- Backward compatibility
- Breaking changes
Quick answer
This API design interview question asks you to design an API versioning strategy. Aim for a design that exposes a clear, consistent and safe interface, then explain the resources, requests, responses and error handling. Interviewers want to see how you name resources, version the interface and handle failure cases.
The problem
Design an API versioning strategy for a public B2B HTTP API used by 4,000 integrations, in the spirit of Stripe's date-based versions. The team makes a breaking change about once a quarter, and today a single /v1 means each one causes an outage for someone.
Breaking changes include renaming fields, splitting an object, changing a default and removing an endpoint, while the team ships changes every week. Design how versions are named, where a client states one, which changes need one, how a request on an old version is served, and how versions are retired.
What must an API versioning strategy do?
- Version selection: A client can state which version it wants on every request; a client that states nothing gets a predictable version.
- Compatibility rules: A written definition of breaking versus non-breaking, with examples, that both the API team and customers can apply.
How well must it do it?
- Safety: A new version can never change what an old version returns.
- Support window: Every version is supported for at least 24 months after the next one ships.
What scale should you design for?
Use these numbers in your estimates.
The scale numbers unlock with this questionUnlock
Key concepts
- API versioning
- Backward compatibility
- Breaking changes
- Deprecation policy
- Sunset header
- Additive changes
How you’ll practise
- Use cases
- Resources
- Endpoints
- Errors, auth and limits
- Versioning
- Wrap-up
Lala, personalized to you, gives a hint when you ask and reviews your design when you are ready.
What do interviewers look for?
In any API design round.
- Starts from the clients and the use cases
- Names resources and operations consistently
- Defines request and response shapes and status codes
- Covers authentication, rate limits and idempotency
- Plans pagination, filtering and versioning
- Explains how clients learn about and recover from errors
Questions people ask about this interview question
- Which design type is this question?
- It is an API design question. You design an API versioning strategy and explain your choices the way you would in an interview.
- Is this question asked at entry level?
- It is marked Easy, so it suits engineers who are new to API design interviews. It is also a good warm-up before harder questions.
- What should I cover first?
- Start with the clients, the main use cases and the resources they need. Agree on scope with the interviewer before you design anything.
- Can I practise it for free?
- It is a premium question. Sign up and unlock it once for 10 credits; it then stays unlocked. When you finish, Lala, your personalized AI mentor, can review your design for 30 credits.
Related questions
Updated · Written by the SevyDevy team