API Versioning: Change APIs Without Breaking Apps

Every API changes eventually. Fields are added, renamed or removed, validation tightens, and old endpoints are retired. For the team that owns the API, each change is a small improvement. For every integration that depends on it, a careless change can mean failed orders, missing records or a broken sync discovered days later. API versioning is the discipline that lets an API evolve while the systems that call it keep working. This guide explains how to tell breaking from safe changes, choose a versioning scheme, announce deprecations clearly and move integrations to a new version without downtime.

Breaking and non-breaking changes

The first step is agreeing what counts as breaking. A change is breaking if a correctly written client that worked yesterday can fail today.

Usually breaking:

• Removing or renaming a field, endpoint or parameter
• Changing a field's type or format, such as a number becoming a string or a date format changing
• Making an optional input required
• Changing the meaning of a value or status code
• Tightening validation so previously accepted requests are rejected
• Changing authentication or permission requirements

Usually safe:

• Adding a new optional field to a response
• Adding a new endpoint
• Adding an optional input parameter with a sensible default
• Relaxing validation

"Usually" matters. Adding a field is safe only if clients ignore fields they do not recognise. Strict clients that reject unknown fields will break, which is why client guidelines matter as much as server rules.

Choose an API versioning scheme

Common approaches:

• Version in the URL path, such as /v1/orders and /v2/orders. Clear, easy to route and easy to see in logs.
• Version in a header, such as a custom version header or a media type parameter. Keeps URLs stable but is less visible.
• Date-based versions, where each client is pinned to the API as it was on a given date and upgrades deliberately.
• No explicit versions, with a strong commitment to backward compatibility and long deprecation windows.

There is no single right answer. What matters is consistency across the API and a clear policy on how long old versions live. For libraries and SDKs, Semantic Versioning gives a widely understood rule: increment the major version for incompatible API changes, the minor version for backward compatible functionality and the patch version for backward compatible fixes.

Announce deprecations clearly

Clients cannot adapt to changes they do not know about. Good deprecation practice includes:

• A published changelog and a deprecation policy that states minimum notice periods
• Direct notice to known integrators, ideally identified from API keys or client IDs
• Machine-readable signals in responses

Two HTTP headers help with the last point. RFC 9745 defines the Deprecation header, a standards-track field that tells clients a resource is or will be deprecated. RFC 8594, an informational RFC, defines the Sunset header, which signals when a resource is expected to become unresponsive. Clients and monitoring tools can watch for these headers and alert teams before anything breaks.

Move integrations without downtime

When you are the client, moving to a new API version is a small migration. A safe sequence:

1. Inventory every place the old version is called, including scheduled jobs, scripts and middleware flows
2. Read the changelog and list each change that affects your use
3. Update field mappings, validation and error handling in a branch, with tests against the new version
4. Run both versions in parallel where possible, comparing results on real traffic or a copy of it
5. Switch traffic gradually, for example one flow or one region at a time
6. Keep the ability to switch back until the old version is retired
7. Remove old code once the switch is complete

The same principles as zero-downtime deployments apply: small steps, parallel running and fast rollback. Our guide to Kubernetes zero downtime deployment covers those deployment techniques for the services that host integrations.

Design integrations that tolerate change

Integrations break less often when they are built defensively:

• Ignore unknown fields in responses rather than rejecting them
• Validate only the fields you actually use
• Pin to an explicit version rather than "latest"
• Log the API version used on each call
• Watch for Deprecation and Sunset headers and warnings in responses
• Keep field mappings in configuration, so small changes do not need code releases

Our guide to Zoho CRM integration architecture shows how these practices fit a wider integration design.

Worked example: an API versioning plan

The table below shows a hypothetical plan for retiring version 1 of an internal orders API used by three integrations. Dates are expressed relative to the announcement and are illustrative.

StepTimingActionOwnerAnnounceWeek 0Publish v2 docs, changelog and v1 retirement dateAPI teamSignalWeek 0 onwardAdd Deprecation and Sunset headers to v1 responsesAPI teamInventoryWeeks 1 to 2Each client team lists v1 calls and affected fieldsIntegration ownersBuild and testWeeks 2 to 6Update mappings and tests against v2 sandboxIntegration ownersParallel runWeeks 6 to 8Compare v1 and v2 results on live trafficIntegration ownersSwitchWeeks 8 to 10Move flows to v2 one at a timeIntegration ownersMonitorWeeks 10 to 12Track remaining v1 calls by client IDAPI teamRetireWeek 12Return a clear error from v1API team

The monitoring step matters most: retiring a version while an unknown script still calls it is how most versioning incidents happen.

Common API versioning mistakes

• Treating "we only added a field" as automatically safe without checking strict clients
• Retiring versions without tracking who still uses them
• Announcing changes only on a web page nobody watches
• Supporting so many old versions that every change becomes expensive
• Versioning individual endpoints inconsistently, so clients mix versions by accident

Test against the new version early

Most providers publish new versions in a sandbox or preview before old ones are retired. Point a copy of your integration at the new version as soon as it is available and run your existing tests. Early testing turns an urgent migration into routine maintenance, and it gives you time to raise questions with the provider while the new version can still change.

Keep versions few and short-lived

Each supported version costs testing, documentation and support. Aim to support a small number of versions at once, with a published lifetime for each. Clear rules make planning easier for both sides: integrators know how long they have, and API owners know when old code can go.

Frequently Asked Questions

What is API versioning?

It is a way of managing changes to an API so existing clients keep working, usually by labelling incompatible versions and giving clients time to move between them.

What counts as a breaking API change?

Any change that can make a correctly written client fail, such as removing or renaming fields, changing types, adding required inputs or tightening validation.

Should the version go in the URL or a header?

Either can work. URL versions are visible and simple to route; header versions keep URLs stable. Consistency and a clear lifetime policy matter more than the location.

How do you retire an old API version safely?

Announce it with notice, signal it in responses with Deprecation and Sunset headers, track remaining callers, help them migrate and retire only when usage reaches zero or the notice period ends.

Keep integrations working through change

We plan API version moves, update integrations safely and build connectors that tolerate change. See our CRM and API integration services, or talk to us about API versioning.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.