Versioning an API you will still be calling in 2036

A consumer API that ships monthly can afford to break it. A core banking interface, a claims platform or a manufacturing execution system has a service life measured in decades, and the team that maintains it has long since moved on.

That changes what "versioning" has to mean.

URL versioning does not fit a decade

The familiar pattern is /v1/accounts becoming /v2/accounts. It is legible, and for a twelve-month lifespan it is perfectly adequate.

Over twenty years it produces something worse: a stable prefix with an unstable contract underneath. Consumers pin to /v2, assume stability, and then a field is added or a nullability changes. Ten years later, nobody remembers whether null was ever valid.

The version in the URL becomes a lie the API tells about itself.

Version the contract, not the endpoint

For long-lived internal APIs, a more durable approach is to version the things that actually break consumers:

Additive changes need no version at all. New optional fields, new endpoints, new enum values that consumers must tolerate. Publishing an explicit rule — consumers must ignore unknown fields and must tolerate unknown enum values — removes most of the reason for versioning.

Breaking changes get an explicit, named contract version. Recorded in a schema file in the repository, versioned with the schema, and enforced by contract tests.

Deprecations get a published sunset date and a migration guide, with a named owner. A deprecation without an owner is a rumour.

The practical shift is that consumers pin to a schema, not a URL. The URL can stay stable indefinitely while the schema underneath evolves under them.

Make the change log the primary artefact

For a system with a decade of consumers, the most valuable document is not the API reference. It is a chronological record of every change, every deprecation, and what a consumer had to do about it.

Structure it as: date, change, affected consumers, required action, deadline. It becomes the input to a consumer's own upgrade planning, which they will not otherwise do.

Contract tests are what make it real

A schema file that nothing enforces is a document. A contract test suite that runs on every change in both provider and consumer is a guarantee.

Minimum viable coverage:

• provider tests assert the API never returns a shape the schema forbids
• consumer tests assert the consumer handles the documented shapes, including the edge cases
• a compatibility check in CI that fails on a breaking change without a version bump

That last one is what prevents the accidental break. It has to be automated, because the person making the change will not see it as breaking and the person who remembers the old contract has left.

Deprecate slowly, on purpose

For a long-lived API, a deprecation policy that actually works looks like:

• a published minimum notice period, six months as a floor
• usage telemetry showing which consumers still depend on the deprecated item
• direct contact with the specific consumers who have not migrated
• a hard sunset date, honoured

The most common real-world failure is a deprecation that is announced and then never enforced, because enforcing it would break an internal team. That teaches every consumer that the policy is optional.

Handle the consumers you will never meet

Internal APIs acquire consumers through accident. A report reads a view directly. A script written during an incident becomes a scheduled job. Nobody knows they exist.

This is the strongest argument for monitoring every endpoint and field rather than only the documented ones. Access logs are how you discover the consumers you cannot contact — and they are the only way to know a deprecation can safely proceed.

The practical summary

• Write the contract as a versioned schema in the repository
• Enforce it in CI, in both directions
• Publish additive-change and enum-tolerance rules
• Maintain a dated change log with named owners
• Monitor access to find the consumers nobody documented
• Enforce deprecation dates, even when it is inconvenient

None of this is more work than version-in-the-URL. It is more work than doing nothing, which is what most long-lived internal APIs do.