Skip to content
← All articlesEngineering

API Versioning and Deprecation Strategy for Product Teams

How to version and retire APIs without breaking clients: versioning options, breaking-change rules, sunset policies and a checklist for outsourced teams.

Sooner or later every successful API has to change. A field gets renamed, a response shape turns out to be wrong, a pricing model needs a new object. The trouble is that you rarely control every client. Mobile apps stay on old versions for months, partners integrate once and forget, and customers write scripts you never hear about. A clear API versioning and deprecation strategy is what lets you keep improving the product without causing outages for the people who depend on it.

This guide is written for CTOs, founders and product managers who commission APIs, whether in-house or with an outsourced team, and want change to be boring rather than risky.

Start by avoiding versions you do not need

The cheapest version bump is the one you never make. Most changes can be made additively, and additive changes do not require a new version:

  • Adding a new optional request field
  • Adding a new field to a response
  • Adding a new endpoint
  • Adding a new value to a response field, provided clients were told to tolerate unknown values

Put one rule in your API guidelines and in your contract with any development partner: clients must ignore fields they do not recognise. Without it, even additive changes can break strict parsers.

What counts as a breaking change

Agree on a written definition. A change is breaking if a correctly written existing client could fail after it. Typical examples:

  • Removing or renaming a field, endpoint or query parameter
  • Changing a field’s type, format or meaning (for example, price in pounds becoming price in pence)
  • Making an optional request field required
  • Tightening validation so previously accepted input is rejected
  • Changing error codes or status codes that clients branch on
  • Changing authentication or authorisation requirements
  • Changing default sorting or pagination behaviour

Meaning changes are the most dangerous because nothing looks different in the schema. Review them as seriously as removals.

Versioning approaches compared

Approach Example Strengths Trade-offs
URI path /v2/orders Obvious, easy to route, easy to test in a browser Version spreads across every resource; encourages large version jumps
Custom header API-Version: 2026-11-01 Clean URLs; supports date-based versions Less visible; harder to try manually; caches must vary on the header
Media type Accept: application/vnd.example.v2+json Fits REST purists’ view of representations Awkward tooling and documentation
Query parameter /orders?version=2 Simple to add Easy to forget; can pollute caching and logs

For most products, URI path versioning is the pragmatic choice. It is easy for partners and mobile developers to understand and straightforward to document. Date-based header versioning can work very well for mature public APIs, but it needs more discipline and tooling. Whichever you pick, choose it once and apply it consistently. Mixed schemes are a common source of confusion in inherited codebases.

Version the contract, not every deployment. A major version should change rarely, perhaps every year or two, and should bundle several breaking changes together so clients migrate once.

Design your deprecation policy before you need it

A deprecation policy is a promise, so write it down and publish it:

  1. Announce early. State when a version or field is deprecated, what replaces it and when it will be removed.
  2. Give a realistic window. Pick a minimum support period that matches your clients. Partner integrations and mobile apps need longer windows than internal services.
  3. Signal in the API itself. Return a Sunset HTTP header (defined in RFC 8594) with the removal date, and a Deprecation header or a link to migration notes, so developers see warnings in their own logs.
  4. Notify humans too. Email registered API consumers, post in the changelog and update the documentation.
  5. Measure usage. Log which clients call deprecated endpoints so you can contact them directly before shutdown.
  6. Remove deliberately. Before removal, consider brownouts, which are short planned periods where the old version returns errors, to flush out forgotten callers.

Mobile apps need extra care

Web clients update the moment you deploy. Mobile clients do not. An app released a year ago may still be in use, so an API removal can break real users with no way to hotfix them. Plan for this by combining version support windows with a force-update mechanism, which we cover in our guide to mobile app force update and API compatibility. Track the share of traffic per app version and retire an API version only when that traffic is genuinely negligible.

Make it testable

Versioning rules that live only in a wiki will be broken under deadline pressure. Automate them:

  • Generate an OpenAPI description from the code or maintain it as the source of truth.
  • Run a breaking-change diff in CI that fails the build when the schema changes incompatibly within a version.
  • Use consumer-driven contract tests where you know your consumers.
  • Keep automated tests for each supported version until it is removed.

Keep the maintenance cost visible

Every supported version is code to maintain, secure and test. Avoid copying whole codebases per version. Instead, keep one core domain model and translate at the edge, with thin adapters converting between the current model and each older response format. Track how many versions are live and put sunset dates in the backlog so that old versions actually get removed.

A practical checklist

  • Written definition of a breaking change
  • “Clients must ignore unknown fields” documented
  • One versioning scheme, applied consistently
  • Published deprecation policy with minimum notice period
  • Sunset header and changelog entries for every deprecation
  • Per-client usage logging on deprecated endpoints
  • Breaking-change check in CI
  • Mobile traffic by app version reviewed before removal

Getting it right with your development partner

If you outsource backend work, put these rules into the statement of work so they are acceptance criteria rather than good intentions. Our guide to REST API design best practices covers the wider design decisions that make versioning easier.

AkMo Technologies designs, builds and maintains APIs for web and mobile products. Learn more about our web development services, or contact us to discuss an API you are planning or need to evolve safely.

Let’s build what’s next.

Tell us about your platform, your product idea or the systems you want to modernise. Someone from our Chennai engineering team will get back to you personally.