API Versioning for Business Integrations: Changing Without Breaking Your Partners
November 11, 2026 · 7 min read · Etzal Group Team
A distributor's ERP exposes an interface that three marketplaces, a logistics partner and the company's own mobile app use to read stock and place orders. One afternoon a developer tidies up the stock response, renaming "qty" to "quantity" and changing the date format. Everything passes the internal tests. That evening, orders from one marketplace stop arriving, the logistics partner's system shows every item as out of stock, and older versions of the mobile app crash on opening. Nothing was broken in the ERP. A contract was broken. API versioning is the discipline of changing an interface without doing that.
An API is a promise
When another system depends on your interface, its shape is a commitment: these addresses, these inputs, these outputs, these meanings. The other side has written code against it and may not look at that code again for a year.
You control your system. You do not control when theirs changes. Versioning exists to bridge that gap.
What breaks and what does not
Usually safe, backward-compatible changes:
- Adding a new endpoint.
- Adding a new optional input.
- Adding a new field to a response.
- Adding a new value where consumers were told to expect new values.
- Making a required input optional.
- Performance improvements.
Breaking changes:
- Removing or renaming a field or endpoint.
- Changing a type: number to text, single value to list.
- Changing a format: dates, decimal separators, units, currency.
- Making an optional input required.
- Changing what a value means. "Status 2" used to mean shipped and now means packed.
- Changing default behaviour: sort order, page size, what is included when no filter is given.
- Tightening validation, so that input once accepted is now rejected.
- Changing error codes or the structure of error responses.
- Changing authentication or permissions.
- Changing when things happen: an operation that was immediate becomes delayed.
Two cautions. Adding a field is safe only if consumers ignore fields they do not recognise, so say in your documentation that they must. And changes in meaning are the most dangerous, because nothing fails visibly. The data is simply wrong.
Three ways to version
1. In the address. /v1/orders and /v2/orders.
Clear, visible and easy to route. The most common choice for business integrations, and the easiest for partners to understand.
2. In a header. The address stays the same, and the consumer states the version it wants in a request header.
Cleaner addresses and finer control. Less visible, and easier for a partner to get wrong.
3. By date. Each consumer is pinned to the version of the interface as it was on a given date, and opts in to newer behaviour.
Suits providers with many consumers and frequent small changes. Requires more machinery on the provider's side.
For a mid-sized company integrating with a handful of partners, versioning in the address with whole-number versions is usually enough. What matters more than the method is having one and following it.
Avoid needing a new version
A new major version is expensive for everyone. Most change can be made without one.
- Add, do not alter. Need a different format? Add a new field beside the old one. Keep both for a period.
- New behaviour behind a new option. Existing callers who do not send it get the old behaviour.
- Design for growth from the start. Return objects, not bare lists or values, so fields can be added later. Use text codes for statuses, and tell consumers that new ones may appear.
- Be strict in what you promise. Document only what you intend to keep. Anything undocumented that consumers come to rely on becomes a promise anyway.
- Do not expose your database. An interface that mirrors internal tables breaks every time the tables change. Design the interface around what partners need, and translate inside.
A well-designed interface can run for years on version 1.
When a new version is right
- The existing design is wrong in a way additions cannot fix.
- A security problem requires changed behaviour.
- A business rule has changed fundamentally.
- Accumulated additions have made the interface confusing.
Then make the new version worth the migration: fix several things at once, and do not release a new major version every few months.
Retiring an old version
Deprecation is a process with dates.
- Announce. When the new version is released, publish the retirement date of the old one. Give partners six to twelve months, or more if their release cycles are slow.
- Document the migration. A guide listing every difference, with before-and-after examples.
- Signal in the responses. Mark the old version as deprecated in response headers, with the retirement date.
- Measure usage. Log which consumer calls which version. You cannot retire what is still in use without knowing who you will break.
- Contact those who have not moved. Directly, by name, well before the date. Announcements are not read.
- Rehearse the end. Shortly before retirement, switch the old version off for an hour at an announced time. Anyone who missed every notice will find out while there is still time.
- Retire. Return a clear error that names the new version.
Retiring a version nobody uses is easy. The work is knowing that nobody uses it.
Know your consumers
- Issue each consumer its own credentials. Shared keys make it impossible to tell who is calling.
- Keep a register: consumer, contact person, which endpoints and versions they use, when they last called.
- Keep the contacts current. The developer who built the integration two years ago may have left.
When a change is planned, this register is your list of people to tell.
Test the contract
- Contract tests. Automated tests that check the interface still returns what its specification promises. Run on every change.
- A specification as the source of truth. A machine-readable description of the interface, from which documentation and tests are generated.
- Compatibility checks. Tools that compare the new specification with the old and flag breaking changes before release.
- A sandbox for partners. A test environment where partners can try the new version with safe data.
The developer in the opening story would have been stopped by a single contract test asserting that the stock response contains "qty".
Mobile apps are consumers you cannot update
Your own mobile app is a special case. Users update when they choose, and some never do. Old versions keep calling your interface for months or years.
- Support old app versions for a defined period.
- Build a "please update" mechanism into the app from the first release, so the server can tell an old version it is no longer supported.
- Track which app versions are active before removing anything.
Terms to agree with partners
For integrations between companies, put the expectations in writing.
- Notice period for breaking changes.
- Minimum support period for each version.
- How changes are announced, and to whom.
- Availability of a test environment.
- Who bears the cost of migration.
- Rate limits and fair use.
- Support contacts on both sides.
The same applies when you are the consumer. Ask your partners and vendors how they version and how much notice they give.
Common mistakes
- No versioning at all, until the first break.
- "Small" changes to existing fields.
- Changing meaning without changing structure.
- Shared credentials, so nobody knows who uses what.
- Announcing retirement without measuring usage.
- Too many versions alive at once. Two is manageable. Five is a burden.
- Exposing internal structures directly.
- Forgetting old mobile app versions.
- Documentation that describes what the developer intended, not what the interface does.
We design integration interfaces with a versioning policy and contract tests as part of Enterprise Software. If partners depend on an interface of yours and every release feels risky, contact us.
Summary
Treat an interface that others depend on as a contract. Know which changes break consumers, including silent changes of meaning. Version in the address unless you have reason to do otherwise, and prefer adding to altering so that new versions are rare. Retire old versions by a published timetable, with a migration guide, usage measurement, direct contact and a rehearsal. Give each consumer its own credentials, test the contract automatically, plan for old mobile app versions, and agree notice periods with partners in writing.
Frequently asked questions
What is a breaking change in an API?
Any change that can make existing integrations fail or behave differently without their owners changing anything: removing or renaming a field, changing a data type or format, making an optional input required, altering the meaning of a value, changing error codes, or tightening validation. Adding new optional fields and new endpoints is normally safe.
How long should an old API version be supported?
Long enough for every consumer to migrate comfortably. For integrations between businesses, six to twelve months after the replacement is available is common, and longer where partners have slow release cycles. Publish the retirement date when the new version is released, and track who is still using the old one.
Do internal APIs need versioning?
If the consumer and the provider are deployed together by the same team, less so. As soon as another team, a mobile app that users update at their own pace, or an outside partner depends on the interface, treat it as a contract. Mobile apps in particular keep old versions in use for months.
Related service
Website Development
Fast, SEO-ready websites that turn visitors into customers.
