API Versioning: Keeping Interfaces Long-Lasting

APIs have become the infrastructure of digital commerce. According to Gartner, over 90 percent of new enterprise applications now integrate APIs as a core component of their architecture (Gartner). The API management market is expected to grow from around 10 billion US dollars in 2025 to over 100 billion US dollars by 2033 (Market Data Forecast, 2025). The more systems depend on an interface, the more expensive every uncoordinated change becomes.

The core problem is the coupling between provider and consumer. When the shop renames a data field that a connected ERP system expects, processing breaks -- possibly unnoticed until orders stop arriving. Versioning solves this by providing several state-of-the-art definitions of an interface simultaneously: existing consumers keep working with the old version while new features ship in a new version. This temporal decoupling is the foundation of every maintainable integration and complements the architecture questions we cover in our article on REST API versus middleware.

The most widespread strategy is URI versioning, where the version number is part of the path, such as /api/v1/orders and /api/v2/orders. The big advantage is visibility: every call immediately makes clear which version is being used. This simplifies debugging, logging and caching through proxies and CDNs, since different versions have different URLs.

URI versioning is also the easiest for developers to understand and testable directly in the browser address bar. The Shopware Store API and Admin API work with a version prefix in the path, which fits this model well. The downside: strictly speaking, the same resource should be reachable under a stable URL -- several versions of the same order under different paths contradict pure REST doctrine. In practice, however, pragmatism usually prevails.

With header versioning, the URL stays stable and the desired version is transmitted via an HTTP header -- either through a dedicated header like X-API-Version or through content negotiation in the Accept header. The resource URL thus stays identical across all versions, which is closer to the REST philosophy.

The downside is lower visibility: the version is not recognizable in the URL, which complicates debugging and caching. Header-based versioning also requires disciplined clients that reliably set the header. If a consumer forgets the header, the server must deliver a sensible default version -- and this default choice becomes the critical decision at every version change. Which variant fits depends on the consumer landscape and caching requirements.

A third model uses date stamps instead of sequential numbers, such as version 2026-06-22. This approach has proven itself with large platform APIs, foremost among them Stripe, which has versioned its API by date since 2011 and maintained backward compatibility for over a decade (Stripe Engineering Blog). On the first call, an account is automatically pinned to the current version -- so-called pinning.

The charm of this model lies in its internal design: the core logic only knows the latest version. Older versions are handled by isolated transformation modules that step by step convert a modern response back into the format of older versions (Stripe Engineering Blog). The business logic thus stays free of branches for old versions, and new features emerge without regard for historical schemas. For shop interfaces with many external consumers this pattern can serve as a model, even though it is more demanding to implement.

Semantic versioning (SemVer) structures version numbers according to the MAJOR.MINOR.PATCH scheme. An increase of the major version signals breaking changes, a minor version backward-compatible extensions and a patch pure bug fixes. This scheme communicates the scope of a change through the number alone.

Despite its clarity, SemVer is less common with APIs than one might expect: only 26 percent of teams use semantic versioning, so most track changes without clearly communicating their impact (Postman State of the API 2025). For interfaces, a combination is usually advisable: the major version lands in the URI path (v1, v2), while minor and patch changes ship backward-compatibly within the same major version. Version paths thus stay stable, and only real breaking changes force a new path.

The most effective strategy against version sprawl is to avoid breaking changes in the first place. The principle of tolerance requires that a consumer ignore unknown additional fields rather than responding with an error. A provider can then add new fields without disturbing existing clients. Conversely, a provider should as a rule not retroactively tighten required fields or change data types.

In integration projects this discipline pays off directly: the more changes stay backward-compatible, the less often a new major version must be rolled out -- and the less often consumers have to migrate. Robust error handling in interfaces complements this principle by catching unexpected data formats instead of aborting processing.

No version lives forever. At some point an old interface version should be shut down to reduce maintenance effort. What matters is that this happens in an orderly way and with sufficient lead time. Industry-standard deprecation periods comprise an announcement phase, a migration phase and finally the shutdown; periods of several months up to around two years are common, depending on scope (Gravitee, 2025).

A clean deprecation process follows several stages. First the new version is released while the old one is marked as deprecated but kept running. Then consumers are actively informed and supported in migration. Only after the deadline expires does the shutdown follow, the so-called sunset.

So that consumers do not overlook an impending shutdown, it should be signaled technically. The HTTP standard provides dedicated headers for this: the Deprecation header marks a response as outdated, the Sunset header names the planned shutdown date. Every client thus learns in a machine-readable way, on every call, that the version it uses has an expiry date.

In addition to the headers, a maintained changelog is needed that documents every change, as well as a migration guide that concretely describes the differences between versions. Clear communication is considered a central success factor, since breaking changes can cause significant disruption for dependent systems (Redocly, 2025). Anyone who communicates deprecation purely by email or documentation risks consumers missing the deadline -- machine-readable signals also reach automated clients.

An increasingly preferred philosophy is API evolution: instead of creating a new version for every change, a single version is maintained for as long as possible. Non-breaking changes flow in directly, and only real breaking changes lead to a new version or a new endpoint. Successful platforms combine this approach with explicit versioning for the rare cases in which an incompatible change is unavoidable (Speakeasy, 2025).

This hybrid approach noticeably reduces the number of parallel versions and thus maintenance effort. Fewer versions mean fewer code paths, fewer tests and less confusion for consumers. For shop interfaces meant to run stably for years, the goal is therefore not as many versions as possible, but as few version changes as possible with high backward compatibility.

To keep accidental breaking changes from reaching production in the first place, contract testing helps. It automatically checks whether an API still fulfills its documented contract -- such as an OpenAPI specification. If a field type changes or an endpoint disappears, the test fails already in the development pipeline before consumers are affected.

In addition, monitoring version usage provides the data basis for deprecation decisions. When it is measurable how many consumers still use an old version, the shutdown can be planned in a well-founded way instead of guessed. A central middleware gateway is well suited to capture version usage, error rates and latencies per version in one place. This observability is the prerequisite for shutting down old versions without surprising active consumers.

In the practice of shop-ERP integration, several versioned worlds meet: the Shopware API, the API of the ERP system such as SAP or Dynamics and possibly a custom integration layer. Each of these interfaces has its own version lifecycle, and updates rarely happen synchronously.

This is where the value of an interposed integration layer shows: it encapsulates the version differences of the connected systems. When the ERP system releases a new API version, only the corresponding connector in the integration layer is adjusted, while the shop continues working unchanged. This decoupling is the same principle we cover in detail in our article on REST API versus middleware -- applied to the problem of diverging version cycles. In our experience, the third or fourth connected system with its own version schedule arrives sooner than most companies initially assume (project experience).