What is API versioning and why is it needed?
API versioning is a way to make changes to an API without breaking the apps that already use it. When you need to change how the API behaves, you release a new version and let old clients keep using the old one. The most common approach is putting the version in the URL, like /v1/users and /v2/users.
- Versioning lets an API change without breaking existing clients.
- Common approaches are URL versioning, header versioning, and query parameters.
- A clear versioning strategy supports smooth upgrades over time.
Why it matters
Once other apps depend on your API, changing a field or removing an endpoint can break them. Versioning lets you introduce breaking changes safely by offering a new version while the old one keeps working.
- URL versioning: /v1/users, simple and easy to see.
- Header versioning: the client asks for a version in a request header.
- You keep the old version alive until clients migrate.
Point out that you only bump a version for breaking changes, not for adding new optional fields. Showing you know when versioning is and is not needed reflects real experience.
Frequently asked questions
What is the most common way to version an API?
URL versioning, such as /v1/users, is the most common because it is simple, visible, and easy for clients to understand and cache.
When do you need a new API version?
When you make a breaking change, such as removing a field or changing its meaning. Backward compatible additions usually do not need a new version.
Common follow up questions
Related interview questions
Want the full API Design guide?
Read every API Design concept with notes, diagrams, and code in one place. Track your progress as you go.
Open the API Design guide All API Design questions