The API Breaking Change Checklist Every Team Needs

Not all API changes are created equal. Some are perfectly safe — additive, backward-compatible, invisible to existing consumers. Others silently break integrations, trigger production incidents, and erode the trust your API consumers have in your platform. The difference between the two is not always obvious.

This checklist exists to remove the guesswork. Whether you are reviewing a pull request, planning a migration, or trying to decide if a change warrants a major version bump, use this as your reference. It covers every category of breaking change we have seen cause real-world incidents.

What Makes a Change "Breaking"

A breaking change is any modification to a public API that can cause existing, correctly-written client code to fail. The key word is existing. If a consumer built an integration against your documented API contract and followed it correctly, a breaking change is anything that makes their code stop working without them changing a single line.

A non-breaking change, by contrast, is one that existing consumers can safely ignore. Adding a new optional field to a response, introducing a new endpoint, or supporting an additional query parameter — these are additive changes that do not affect existing behavior.

The distinction matters because breaking changes require coordination: versioning, migration guides, deprecation timelines, and consumer notification. Non-breaking changes can ship continuously.

The Checklist

Response Body Changes

Removing a field — Any field removal is breaking. Consumers may depend on fields you consider unimportant.
Renaming a field — This is equivalent to removing one field and adding another. Consumers parsing the old name will break.
Changing a field's type — Changing a string to an integer, an object to an array, or any other type mutation will break deserialization in typed clients.
Changing a field from optional to required — Safe in most cases, since consumers already handle the field's presence. However, changing from required to optional (or returning null where a value was always present) is breaking.
Restructuring nested objects — Moving a field from the top level into a nested object, or flattening a nested structure, breaks field access paths.
Changing enum values — Removing or renaming values in an enum field breaks consumers who match against those values.

// Before: consumers rely on "status" being a string at the top level
{
  "id": 42,
  "status": "active",
  "owner": "acme-corp"
}

// After: "status" moved into a nested object — this is breaking
{
  "id": 42,
  "details": {
    "status": "active"
  },
  "owner": "acme-corp"
}

Request Changes

Adding a new required parameter — Existing requests that omit this parameter will start failing.
Removing a previously accepted parameter — If consumers send a parameter you no longer accept and your API returns an error, that is breaking.
Changing parameter types — Expecting an integer where consumers send a string will cause validation failures.
Changing validation rules — Tightening validation (shorter max length, stricter format, narrower value range) rejects previously valid requests.
Changing a parameter from optional to required — Existing requests that omit it will fail.

URL and Routing Changes

Changing a resource path — Moving /api/users to /api/v2/accounts breaks every hardcoded URL and client configuration.
Removing an endpoint — The most obvious breaking change. Consumers get 404s.
Changing the HTTP method — Switching an endpoint from POST to PUT or GET to POST breaks existing client calls.
Changing path parameter names or structure — Moving from /users/{id} to /users/{userId} can break client libraries that use named parameters.

Status Code Changes

Changing success status codes — Switching from 200 OK to 201 Created or 204 No Content breaks consumers who check status codes explicitly.
Changing error status codes — If consumers handle 404 differently from 400 and you swap them, their error handling logic breaks.
Changing error response format — Restructuring your error object (renaming message to error, nesting details differently) breaks error parsing.

// Before: consumers parse this error structure
{
  "error": "not_found",
  "message": "User does not exist"
}

// After: restructured errors — consumer parsing breaks
{
  "code": "NOT_FOUND",
  "details": {
    "description": "User does not exist"
  }
}

Authentication and Authorization Changes

Adding authentication to a previously public endpoint — Unauthenticated consumers start getting 401s.
Changing the authentication mechanism — Switching from API keys to OAuth, or changing token formats, breaks existing auth flows.
Requiring new scopes or permissions — Existing tokens without the new scope get rejected with 403s.
Changing token expiration behavior — Shorter expiration times can cause previously working long-lived integrations to fail.

Header Changes

Requiring a new request header — Requests that omit the header will fail.
Removing a response header — Consumers who read rate-limit headers, pagination cursors, or correlation IDs from response headers will break.
Changing content type — Switching from application/json to application/xml or changing charset encoding breaks response parsing.

Behavioral Changes

Changing default pagination — Reducing default page size or switching from offset-based to cursor-based pagination breaks iteration logic.
Changing sort order — If a list endpoint changes its default ordering, consumers who rely on the previous order see different results.
Changing rate limits — Stricter rate limits cause previously successful request patterns to get throttled.
Changing the meaning of a field — If count used to mean "total items" and now means "items on this page," the contract has changed even though the field name and type are identical.
Changing side effects — If a POST endpoint used to send an email and no longer does (or vice versa), integrations that depend on that behavior are broken.

The Gray Area

Some changes are technically non-breaking but cause breakage in practice because of how consumers actually use APIs — which does not always match your documentation.

Adding new fields to a response — Technically safe, but consumers using strict deserialization (common in statically typed languages with strict JSON parsers) may reject unknown fields.
Adding new enum values — If consumers have exhaustive switch statements over your enum, a new value causes an unhandled case.
Adding new error codes — New error types that consumers do not handle can fall through to unexpected code paths.
Changing performance characteristics — A query that used to return in 200ms now takes 5 seconds. No contract violation, but timeouts start firing.
Changing the precision of numeric values — Returning more decimal places or switching from 32-bit to 64-bit integers can cause overflow in some clients.

The right approach to gray-area changes depends entirely on your consumer base. If you control all consumers, you can coordinate. If your API is public, treat gray-area changes as potentially breaking and communicate them accordingly.

Putting This Checklist to Work

Most teams review API changes against a mental model of what might break. That works until it does not — usually at the worst possible time, when a change that seemed harmless cascades into a production incident across multiple consumer services.

The discipline is straightforward: every pull request that touches an API surface should be evaluated against this checklist. The question is whether you do that manually on every review, or whether you automate the detection so your team can focus on deciding what to do about the changes rather than trying to spot them in a diff.

Either way, the checklist does not change. These are the categories. These are the failure modes. The only variable is whether you catch them before or after your consumers do.