Keeping API Contracts From Breaking Between Services

Put a version in the URL path or a header from the very first release, even when there's only one consumer. Retrofitting versioning after three teams depend on an unversioned endpoint is far more painful than starting with it, because now every change has to be backward compatible by accident instead of by design.

A simple rule works for most teams: additive changes, new optional fields, new endpoints, ship without a version bump. Anything that removes a field, changes a type, or changes required behavior gets a new version, with the old one supported until every known consumer has moved.

The team that owns the service publishing the API owns the contract, full stop, but that only works if consumers have a clear, low-friction way to request a change instead of just calling the owning team's Slack channel and hoping.

A short RFC process, even a one-page doc and a 48-hour comment window, forces the conversation to happen before the breaking change ships instead of after it's already in production and someone's dashboard is red.

Manual contract review catches maybe half of what breaks. Automated schema validation, run against every pull request that touches a public interface, catches the rest: the field that changed type, the required property that quietly became optional, the enum value that got removed.

Consumer-driven contract tests take this further, letting each consuming service assert what it actually depends on, so a producer's CI run fails immediately if a change would break a real consumer instead of an assumption about what might be out there.

Say a billing service adds a new required field to its webhook payload to support a new plan type. Internal consumers get updated in the same release. An external partner integration, built against the old shape, starts failing validation on every event and silently drops them, since webhook failures rarely page anyone the way an API error would.

Nobody notices until the partner asks why their records stopped updating two weeks later. Making the new field optional with a sensible default, or versioning the webhook payload the same way as the API, would have kept old consumers working while the new field rolled out.

• A breaking change shipped because the team assumed nobody else was calling that endpoint
• Documentation that describes the API as it was six months ago, not as it is today
• No deprecation timeline, so an old version lingers forever because removing it feels risky
• Internal and external consumers held to different standards, so external partners break more often

Most of these come from treating internal APIs as informal, when the actual blast radius of breaking one is often larger than an external partner integration.

Documentation that lives in a separate wiki drifts from reality within a few releases. Generating docs from the schema itself, an OpenAPI spec, protobuf definitions, whatever your stack uses, means the documentation can't drift further than the schema does, because it's the same artifact.

This also gives you a free source of truth for the contract tests described above: the schema becomes both what's documented and what's enforced, instead of two things maintained separately that quietly disagree.

Not every breaking change is a mistake. Sometimes the old shape is actively wrong, a field encodes the wrong unit, an enum is missing a value the business now needs, and holding onto it forever just preserves the bug for new consumers too.

The difference between a planned break and an accidental one is whether it goes through the same version bump and deprecation window as everything else. Give the old version a real end date, tell every known consumer directly instead of relying on a changelog nobody reads, and confirm the last of them has moved before you delete it. A break that follows the process is a normal part of running a system for years. A break that skips it is the incident this whole standard exists to prevent.