NexisyTech Learningby Nexisy Technologies

API Versioning

Evolve an API without breaking the clients that already depend on it.

Beginner6 min read3 interview questions

Once an API is public, every field, URL and status code is a promise. Versioning lets you introduce breaking changes as a new version while existing clients keep working.

The best strategy is to avoid breaking changes in the first place — add fields, don’t rename or remove them — and version only when you must.

Diagram

v1v2Old mobile appNew web appRouterreads version/api/v1/ordersdeprecated, sunset 2027/api/v2/orderscurrent
Old and new clients run side by side on different versions until v1 is retired.

Key concepts

URI versioning
/api/v2/orders. Visible, easy to route and cache. The most common choice.
Header versioning
Api-Version: 2 or a custom media type. Clean URLs, less visible.
Query string
?api-version=2. Simple; used by Azure APIs.
Breaking change
Removing or renaming a field, changing a type or status code, or making an optional field required.
Deprecation policy
Announce, add Deprecation and Sunset headers, monitor usage, then retire.

Trade-offs

Benefits

  • Clients upgrade on their own schedule
  • Teams can redesign without fear

Costs

  • Every live version must be maintained, tested and secured
  • Too many versions fragment the codebase

Use it when

  • Public and partner APIs, and APIs used by mobile apps that update slowly

Common mistakes

  • Creating a new version for an additive change
  • No usage metrics per version, so old versions can never be retired
  • Copy-pasting the whole codebase per version instead of sharing the core logic

Interview questions

Q1Is adding a new optional field to a response a breaking change?
Normally no, as long as clients ignore unknown fields — which they should be told to do. Removing or renaming a field is breaking.
Q2How would you retire v1 of an API?
Publish a sunset date, return Deprecation/Sunset headers, contact heavy users, track v1 traffic, and switch it off only when usage is near zero.
Q3Why might mobile apps need longer support for old versions?
Users don’t always update apps, so old versions keep calling the API for months or years.

Related lessons

APIs & Security

API Architecture Styles

REST, GraphQL, gRPC, WebSockets, webhooks and SOAP — what each is for.

Beginner10 min read APIs & Security

API Gateway

A single front door that routes, secures and shapes traffic to your back-end services.

Intermediate8 min read Cloud & Delivery

Deployment Strategies

Rolling, blue-green, canary and feature flags — release without downtime and roll back fast.

Intermediate8 min read