An enterprise platform supports many years of API versions simultaneously because customers integrate deeply and upgrade slowly. What does that policy cost, and what would you do differently?

What the policy buys

Customer trust and enterprise viability. An enterprise customer with hundreds of integrations built over a decade cannot re-certify them because a vendor wants to tidy its API. A long support commitment is frequently the reason such customers commit at all, and breaking it once destroys credibility that took years to build.

What it costs

Every version is a live code path. Behaviour must be preserved exactly, including bugs that customers have worked around — and their workaround breaks if you fix the bug.

The test matrix multiplies. Every change must be validated against every supported version, which grows the cost of every future change.

Internal refactoring is constrained by the oldest version. A data model change must be expressible in the semantics of an API written many years ago. This is the deepest cost, because it is invisible: the platform simply becomes slower to change, and no one can point at the reason.

New capabilities are hard to expose coherently when the surface must remain comprehensible across many versions.

What to do differently

1. Separate the wire contract from internal models rigorously. Versions should be translation layers over one internal model, not parallel implementations. If each version has its own code path into the domain, the cost is quadratic; if each version is an adapter, it is linear.

2. Additive-only evolution wherever possible. New optional fields and new endpoints do not require a new version. Reserve version increments for genuinely breaking changes, which should be rare. Many platforms create versions for changes that did not need one.

3. Measure usage per version and per endpoint. Deprecation is a political problem solved with data: "three customers use this, here they are, here is their migration path" is a conversation. "Some customers might use this" is not.

4. A published deprecation policy with real dates, communicated years ahead, with automated warnings in responses and in developer dashboards. The commitment customers actually need is predictability, not infinite support.

5. Migration tooling, not migration documentation. Compatibility shims, automated diff reports showing what changes for a specific customer's usage, and sandbox environments running the new version against their integration. The cost of migration is what makes customers refuse, so reducing it is the highest- leverage intervention.

6. Version at the field level where possible. A deprecated field with a machine-readable notice, whose actual usage can be measured, is far more manageable than a whole-surface version.

The judgement

The policy is defensible for the market it serves; the mistake is treating long support as a substitute for a deprecation process rather than as a longer runway within one. Without measurement, tooling and published dates, "we support old versions" becomes "we support all versions forever", and the platform's ability to evolve quietly ends.