How to Manage API Versioning

An API version is a labelled, stable snapshot of how your system accepts requests and returns data. When you change the structure of those requests or responses in a way that would break existing consumers, you need a versioning strategy so that older integrations continue to work while new or updated ones adopt the changes.

The distinction that matters for business planning is the difference between a breaking change and a non-breaking change. Adding an optional field to a response is typically non-breaking: existing consumers simply ignore it. Renaming a field, removing it, or changing its data type is breaking: anything built against the previous structure will fail. Versioning exists to handle the latter without disrupting operations.

There are three widely used mechanisms for communicating which version a consumer wants:

• URL path versioning — the version appears in the endpoint, such as /api/v1/customers. This is the most visible approach and the one most developers reach for first.
• Header-based versioning — the version is sent in a custom HTTP header, leaving the URL unchanged. This keeps URLs clean but makes the version less obvious in logs and documentation.
• Query parameter versioning — the version is appended as a parameter, such as /api/customers?version=1. This is less common and can complicate caching.

For most business systems — CRMs, portals, internal tools — URL path versioning is the pragmatic default. It is easy to read in access logs, straightforward to document, and simple for non-technical stakeholders to understand when reviewing integration reports. The choice between mechanisms is worth agreeing early with your development team, because changing it later means reworking every consumer.

Versioning is not something you need from day one on an internal system with a single consumer. It becomes necessary when you have multiple integrations, external partners, or a SaaS product where customers build against your API. At that point, uncontrolled changes create operational risk that versioning is designed to contain.

When a new version is actually needed

Not every change warrants a new version. Before approving a version bump, ask the development team to confirm that the change is genuinely breaking and cannot be accommodated within the existing contract. Common situations that do require a new version include:

• Removing or renaming a field that existing consumers read.
• Changing a field's data type — for example, from a string to an integer.
• Altering the structure of a response, such as moving a nested object to a different path.
• Changing the meaning of an existing endpoint so that the same request now produces a substantively different result.

Changes that can be made without a new version include adding new optional fields, adding entirely new endpoints, or introducing new query parameters that default to the previous behaviour. A clear internal rule on what counts as breaking reduces unnecessary version proliferation.

Deprecation and sunset timelines

Releasing a new version is only half the process. You also need a deprecation policy for the old one. This means communicating to consumers — through release notes, email, or in-API headers — that a version will be retired on a specific date, and then honouring that timeline.

A typical deprecation period might range from three to twelve months, depending on how many consumers are affected and how often they release updates. Internal systems with a small number of known consumers can usually migrate faster. A SaaS product with dozens of third-party integrations needs a longer runway. The key is that the timeline is published, realistic, and not repeatedly extended — otherwise consumers learn to ignore deprecation notices entirely.

Versioning in SaaS products vs internal systems

For a SaaS product, API versioning is a customer-experience decision. Your customers may have built internal workflows, reporting, or third-party integrations on top of your API. Breaking those without warning or a migration path damages trust and generates support load. A clear versioning policy, documented in your developer portal, becomes part of your commercial offering.

For an internal business system — say, a CRM that feeds data to a finance tool and a reporting dashboard — versioning is about operational coordination. The number of consumers is known and usually small, so the process can be lighter. But the risk is real: a broken integration between CRM and finance can delay invoicing. Even internally, it is worth labelling versions and planning migrations rather than making changes and hoping nothing breaks.

Questions to put to a supplier or development team

• Which versioning mechanism are you proposing, and why is it suited to our situation?
• How will you distinguish breaking from non-breaking changes in the development process?
• What is the deprecation process, and how will we be notified before a version is retired?
• How many API versions do you realistically expect to maintain in parallel, and what is the ongoing cost of that?
• How will version information appear in our monitoring and logs?

Versioning too early

Starting with v1 in the URL before you have any consumers can create a false sense of structure. If the API is still changing rapidly during early development, you may end up with v1, v2 and v3 before anything is live. A practical approach is to keep the API unversioned during internal development and introduce the first explicit version when you have a stable contract that external or downstream consumers will depend on.

Supporting too many versions simultaneously

Each active version carries a maintenance cost. Bug fixes may need to be applied across multiple versions. Database queries may need to support different response shapes. Testing effort multiplies. Agree a maximum number of concurrent versions — often two or three — and enforce it through deprecation. If a consumer cannot migrate within the deprecation window, that is a separate conversation about support arrangements, not a reason to keep old versions alive indefinitely.

No deprecation policy

Releasing new versions without retiring old ones leads to uncontrolled sprawl. Consumers have no incentive to migrate if the old version keeps working without warning. A deprecation policy does not need to be aggressive, but it does need to exist and be applied consistently.

Insufficient communication

Technical teams sometimes treat version changes as internal housekeeping and fail to notify the business stakeholders who manage the integrations. If your operations team does not know that an API version is being deprecated, they cannot plan the downstream work. Build version changes into your release communication process, not just your developer documentation.

Key checks before releasing a new version

• The change has been confirmed as breaking and cannot be accommodated within the existing version.
• The new version is documented, including differences from the previous version.
• A deprecation notice and timeline have been prepared for the old version.
• Monitoring and logging are configured to distinguish traffic between versions.
• Existing consumers have been identified and notified, with a realistic migration path.
• The development team has confirmed the ongoing maintenance cost of running both versions in parallel.

Limits to recognise before committing

API versioning manages change at the interface level. It does not solve underlying data-model problems. If your customer record structure is fundamentally misaligned with how the business operates, adding a new API version that reshuffles the same fields will not address the root issue. Versioning is a coordination tool, not a substitute for good data design.

Equally, versioning does not replace testing. Before retiring an old version, verify that all known consumers have actually migrated. Relying on assumptions rather than traffic data is a common cause of post-sunset breakages.