How to Document Breaking API Changes Without Breaking Trust

Imagine a developer who builds an integration with your API. They write their code, test it, and deploy it. It works perfectly.

Then, six months later, your engineering team optimizes a database query. The API response time drops from 200ms to 50ms. It is a clear performance win.

But the developer's integration breaks. They had unknowingly built a race condition into their application that depended on your API being slow. When you made it faster, their code failed.

This is Hyrum's Law in action. With a sufficient number of users of an API, it does not matter what you promise in the contract. All observable behaviors of your system will be depended on by somebody. The API specification is the formal contract. But the real contract is everything your users have come to depend on, including the things you never intended to guarantee.

APIs are contracts. Breaking changes violate that contract. Poor communication turns a technical decision into a relationship problem.

The goal is not to avoid breaking changes. Sometimes they are necessary to fix security flaws, remove technical debt, or support new features. The goal is to communicate them in a way that preserves customer relationships and reduces the support burden.

When A Fix Is A Failure

A breaking change is any modification that forces client code to be updated to avoid disruption. The definition sounds simple, but the scope is wider than most teams expect.

Some breaking changes are obvious. If you rename GET /usrs to GET /users, integrations will fail. If you remove an endpoint entirely, integrations will fail. If you add a new required parameter without a default value, integrations will fail.

Other breaking changes are subtle. Changing the data type of a response field from an integer to a string can silently corrupt data in downstream systems. Changing the HTTP status code returned for a specific error condition will break integrations that parse those codes for business logic. Even adding new values to an existing enumeration can be a breaking change if the client application is not designed to handle unknown values gracefully.

LinkedIn's API breaking change policy captures this well. It defines a breaking change as any modification that may require you to make changes to your application in order to avoid disruption to your integration, and it explicitly includes changes to the intended functionality of an endpoint, even when the endpoint signature itself remains unchanged.

Before shipping, run your proposed change against this checklist:

The last row is the one that surprises teams. If your API has enough users, someone has built a dependency on its timing, its error message text, or its response ordering. None of these are guaranteed by your specification, but they are observable behaviors, and observable behaviors get depended on.

The 90-Day Warning

Breaking changes require advance notice. You cannot deploy a breaking change on a Tuesday and tell your customers about it on a Wednesday.

The industry standard is 60 to 90 days of advance notice for most breaking changes. This window gives developers time to read the announcement, schedule the migration work in their sprint planning, write the code, test it against a staging environment, and deploy it to production. At enterprise companies with change control processes, 90 days is often the minimum, not the maximum.

Some platforms set the bar even higher. Salesforce notifies customers at least one year before support for an API version ends. Twilio provided a full year of notice before deprecating their Notify API, and published a migration guide alongside the announcement.

The communication timeline should follow a standard sequence.

Announcement (60–90 days out). Publish a deprecation notice in your changelog, your developer portal, and your API responses. The announcement must clearly state what is changing, why it is changing, and when the change will occur. Vague announcements generate support tickets. Specific announcements generate migrations.

Migration guide release (alongside or shortly after the announcement). The migration guide is the document developers will actually use to fix their code. Publish it as soon as possible. Do not make developers wait for the guide while the clock is already running.

Machine-readable deprecation signals. Add Deprecation and Sunset HTTP response headers to any endpoint scheduled for removal. The Sunset header, standardized by the IETF in RFC 8594, carries the date after which the endpoint will no longer be available. The Deprecation header, defined in the IETF's RFC 9745 draft, signals that the feature is in a deprecated state. Zalando's widely-cited REST API guidelines require both headers during any deprecation phase. These headers allow automated monitoring tools to alert developers without requiring them to read every changelog entry.

Usage monitoring. Track which customers are still calling the deprecated endpoints. This is not optional. If you do not know who is still using the old behavior, you cannot reach out to them, and you will be flying blind when you execute the change.

Targeted reminders (30 days, 14 days, 7 days out). Reach out directly to the customers who have not yet migrated. Email is the minimum. For enterprise customers, a direct message from their account manager is better.

Execution. Ship the breaking change on the announced date. Do not move it earlier. If you need to delay it, announce the delay and update all documentation. Consistency builds trust.

Stripe's approach to API versioning is instructive here. Every request to the Stripe API targets a specific API version, and new versions are only published when breaking changes are introduced. Backwards-compatible changes are applied to the current version without creating a new one. This means developers can upgrade on their own schedule, and breaking changes are always deliberate, never accidental.

What The Migration Guide Actually Needs

The migration guide is the most important artifact in this process. It is the document developers will actually use to fix their code. Most migration guides fail because they describe what changed without explaining how to adapt.

A good migration guide is structured around the developer's task, not the API's changelog. The developer does not care that you renamed a field. They care about what they need to change in their code.

For each breaking change, the guide should include: the old behavior, the new behavior, a code example showing the before state, a code example showing the after state, and any edge cases or migration caveats. If you are removing a field, tell the developer where to get that data instead. If you are changing an authentication flow, provide a working code snippet showing the new implementation in the languages your customers actually use.

The guide must be specific. It must be actionable. It must be accurate.

If the migration guide contains errors, developers will waste hours trying to debug their code, only to realize the documentation was wrong. This destroys trust faster than the breaking change itself. Inaccurate documentation after a breaking change is the second failure, and it compounds the first.

There is also a structural concern that teams underestimate. Documentation drifts. As the API continues to evolve after the breaking change, the migration guide can become outdated. The "new" code examples in the guide can themselves become deprecated. Keeping migration guides synchronized with the current state of the API requires a systematic workflow, not a one-time publishing effort. Treating documentation as code, stored in version control alongside the API specification and updated through the same review process as code changes, is the only reliable way to prevent this drift.

The Emergency Exception

Sometimes you do not have 90 days.

If you discover a critical security vulnerability, you may need to ship a breaking change immediately. If a new legal or regulatory requirement goes into effect, you may need to alter your API behavior without the standard notice window. LinkedIn's breaking change policy explicitly carves out this exception: changes may be made without prior notice if they address critical product bugs, legal, security, or privacy concerns.

In these cases, the communication protocol changes, but it does not disappear.

You must still announce the change. The announcement must clearly explain the severity of the issue that forced the emergency action. Developers are more forgiving of a breaking change they understand than one that arrives with a vague explanation.

You must still provide a migration guide. It must be published simultaneously with the change, not days later. If the guide is not ready when the change ships, developers will open support tickets faster than your team can respond.

After the emergency is resolved, you must rebuild trust. Publish a post-mortem explaining what happened, why the emergency change was necessary, and what steps you are taking to prevent similar situations in the future. The post-mortem is not just a courtesy. It is the document that tells your customers whether you are a team that learns from incidents or one that repeats them.

The support cost of a poorly communicated emergency change is significant. API breakage generates immediate surges in support tickets, forces engineering teams into reactive debugging, and can trigger SLA penalties for enterprise customers. The communication artifacts are not bureaucratic overhead. They are the mechanism that converts a crisis into a managed incident.

The Operational Engine

Most of this process is about communication artifacts. Changelogs, migration guides, deprecation notices, post-mortems. These documents need to be written, maintained, and distributed when breaking changes happen, and they need to be accurate, version-controlled, and delivered through the right channels before the change ships.

This is where Doc Holiday comes in.

Doc Holiday structures the generation of these artifacts from the engineering workflow, requiring human validation at each step to ensure quality and accuracy before publication. When a breaking change is introduced, the platform provides the structure to ensure the corresponding documentation is reviewed against the actual API specification, version-controlled alongside the code, and delivered through the right channels before the change goes live.

The platform is designed to handle both planned and emergency breaking changes without requiring a full technical writing team to execute the communication protocol. It keeps documentation synchronized with the API specification, preventing the drift that turns migration guides into liabilities. For teams shipping at speed, that synchronization is the difference between a managed transition and a support crisis.

Breaking changes are not the problem. Surprising your users with breaking changes is the problem.

The documentation is what converts a disruptive technical decision into a managed transition. The checklist, the timeline, the migration guide, the deprecation headers, the post-mortem: these are not nice-to-haves. They are the operational infrastructure that determines whether your customers migrate successfully or churn.