Breaking API Changes

A breaking API change prevents or disrupts at least some existing clients from relying on the previously supported contract. Identify affected consumers and plan a compatible transition, often through staged migration or API versioning.

An API has a contract: the operations clients can call, the inputs they may send, the outputs they receive, and the behavior they can rely on. A change is breaking if a client that worked under the supported contract may stop working or behave incorrectly after the change.

Common examples include removing an endpoint, renaming a response field, making an optional request field required, changing a field's type, or changing status-code or error behavior that clients depend on. A change can be breaking even if the new behavior seems more logical or secure.

Whether a change is breaking depends on the contract and client assumptions. For example, adding a response field is often compatible, but it can break clients that reject unknown fields. A change to undocumented behavior may still affect real clients, so teams should consider observed usage as well as written documentation.

To manage an incompatible change, teams can preserve the old behavior, introduce a new API version, or provide a migration period with clear communication and monitoring. Versioning is a coordination tool: clients still need a supported path to migrate, and old versions eventually need a retirement plan.

Key points

• Judge compatibility by what existing clients can rely on, not by whether the new design seems better.
• Endpoint removal, field renames, stricter validation, and changed semantics can all be breaking.
• Additive changes are often safer, but consumers may reject unknown fields or values.
• Versioning, staged migration, documentation, and usage monitoring help manage incompatible changes.

Interview questions

What is a breaking API change?

A breaking change is a change that can cause a client relying on the existing supported contract to fail or behave differently. It may affect endpoints, request validation, response fields, status codes, or other documented behavior. Whether a change breaks clients depends partly on how clients parse and use the API. I would assess both the stated contract and actual usage before classifying a change.

You need to rename a response field. How would you roll out the change?

Renaming the field is breaking if clients depend on the old name. I could temporarily return both names, document the replacement, and measure use of the old field before removing it. If the change cannot be staged safely, I would expose it under a new API version and keep the old version available during migration. I would communicate a timeline and use monitoring to guide deprecation.

Is adding a response field a breaking change?

Adding a field is often compatible when clients ignore fields they do not recognize, but that assumption is not universal. Strict schema validation, generated clients, or code that expects an exact object shape can reject the new field. I would check the published contract and representative client behavior, and use compatibility tests where possible. If consumers require a fixed schema, I would coordinate a versioned change instead.

How would you deprecate an endpoint safely?

First, I would define which versions remain supported and identify clients using the endpoint through logs, metrics, or client registration data. I would announce the replacement and deadline, provide migration guidance, and, if practical, keep the old endpoint working during the transition. Monitoring should distinguish old-version traffic and reveal failures or remaining users. I would retire the endpoint only after the agreed support period and migration criteria are met.