14-5 · Chapter 14 · 7 min read

When Changing an API Breaks Things Your Users Didn't Know They Depended On

You deploy a new version of your backend service. The pipeline is green. The logs look clean. Five minutes later, your team chat starts lighting up: the

When Changing an API Breaks Things Your Users Didn't Know They Depended On

You deploy a new version of your backend service. The pipeline is green. The logs look clean. Five minutes later, your team chat starts lighting up: the mobile app is returning empty screens, the web frontend shows missing data, and another team's service is throwing 500 errors on every request.

What happened? You changed a field name from nama to full_name in the API response. It seemed harmless. But the mobile app was parsing that field by name, the web frontend was displaying it directly, and the other team's service was mapping it to their database column. None of them got the memo because you didn't know they existed.

This is the reality of maintaining APIs. Unlike a background worker or a scheduled job that only your team touches, an API has consumers you might not even know about. A mobile app that shipped last year. A partner integration set up by a different department. A frontend that can't be updated until the next app store review. When you change the API, you're not just changing your code. You're changing the contract that other systems rely on.

The Problem You Can't See

The core issue is visibility. In a large organization, a single API endpoint might be consumed by dozens of teams. Even if your API only serves one application, that application might already be in the hands of users who can't update immediately. You can't coordinate a simultaneous release across all consumers. Some of them you don't even know exist.

This is where backward compatibility becomes a practical necessity, not a theoretical ideal. Backward compatibility means that a new version of your API can still serve requests using the same format as the old version. If your /users endpoint used to return a field called nama, the new version can't suddenly rename it to full_name without a transition period. If the page parameter accepted an integer, the new version can't suddenly require a string. These changes break the contract, and broken contracts mean broken consumers.

What Counts as a Breaking Change

Breaking changes come in many forms, and some are more obvious than others. Removing an endpoint is clearly breaking. Renaming a field is breaking. Changing a data type is breaking. Adding a required field to a request body is breaking. Changing the format of error responses is breaking.

But there are subtler ones. Changing the order of fields in a JSON response can break code that relies on array indexing. Adding a new required header can break clients that don't send it. Even changing the HTTP status code for a specific error condition can break logic that checks for exact status values.

Consider this simple example. Your API used to return a user object like this:

{
  "id": 42,
  "nama": "Ani Wijaya",
  "email": "ani@example.com"
}

After your "cleanup" rename, it returns:

{
  "id": 42,
  "full_name": "Ani Wijaya",
  "email": "ani@example.com"
}

To you, it's a better name. To the mobile app that parses response["nama"], it's undefined. To the frontend that displays user.nama, it's blank. To the partner service that maps nama to their database column, it's a silent null. The field still exists in spirit, but the contract is broken.

The tricky part is that these changes often look harmless from the server side. You're just cleaning up, adding a feature, or fixing a naming inconsistency. But from the consumer's perspective, the behavior changed in a way they didn't ask for and can't adapt to without a code change on their end.

Catch Breaking Changes Before They Reach Production

The safest approach is to detect breaking changes automatically in your CI pipeline. You don't want to rely on manual review or hope that someone remembers to check. There are tools designed specifically for this.

If you use an API specification format like OpenAPI, tools like OpenAPI Diff or Spectral can compare the old and new versions of your spec. They flag exactly what changed and whether it's a breaking change. If your framework generates the spec automatically, like FastAPI, SpringDoc, or ASP.NET Core with Swashbuckle, you can run this comparison on every pull request.

The workflow looks like this: when a developer opens a pull request, the CI pipeline builds the new API spec, compares it against the spec from the main branch, and reports any breaking changes. If there are none, the PR can proceed normally. If there are breaking changes, the team can discuss whether the change is truly necessary or if it can be done incrementally.

This shifts the conversation from "I hope this doesn't break anything" to "here is exactly what changed and whether it breaks the contract." It turns an invisible risk into a visible decision point.

When You Can't Avoid Breaking Changes

Not all breaking changes can be avoided. Sometimes business requirements force a redesign. Sometimes the architecture needs to evolve. Sometimes the old design was simply wrong and needs to be replaced.

When you must make a breaking change, API versioning is the standard approach. The idea is straightforward: you maintain multiple versions of your API simultaneously. Old consumers keep using the old version while new consumers adopt the new version. You give everyone time to migrate.

There are several ways to implement versioning, each with trade-offs.

URL versioning is the most common approach. You put the version in the path: /v1/users and /v2/users. It's easy to understand, easy to route, and easy to test. The downside is that URLs become longer, and you're maintaining separate code paths for each version.

Header versioning keeps the URL clean but requires consumers to set a custom header, like Accept: application/vnd.myapi.v1+json. This is more RESTful in theory, but it adds complexity for consumers who need to configure headers correctly.

Query parameter versioning uses something like ?version=1. It's simple but less common because it can clutter query strings and is harder to cache properly.

Whichever method you choose, versioning is not free. Every version you maintain is code you need to run, test, debug, and eventually deprecate. You need a policy for how long old versions will be supported. Six months is common. One year is generous. Whatever you choose, communicate it clearly and well in advance. Give consumers a migration window, not a surprise shutdown.

The Better Path: Design for Evolution

Versioning is a fallback, not a strategy. The better approach is to design your API so it can evolve without needing new versions. This means being deliberate about what you expose and how you expose it.

Don't return fields that consumers don't need. Every field you add to a response is a field someone might depend on. If you're not sure whether a field is useful, leave it out. You can always add it later, but removing it is a breaking change.

Use flexible data types where possible. Accept both strings and numbers for parameters that could reasonably be either. Return extra fields in responses without requiring consumers to use them. The principle is simple: be liberal in what you accept and conservative in what you promise.

When you need to add new functionality, add new fields or new endpoints. Don't modify existing ones. A new field in a response doesn't break old consumers because they simply ignore it. A new endpoint doesn't break old consumers because they never call it. As long as you don't remove or rename existing things, you can keep evolving without version bumps.

Practical Checklist for API Changes

Before you merge that pull request, run through these checks:

Did you remove or rename any existing field, parameter, or endpoint?
Did you change the data type of any existing field or parameter?
Did you add a required field to the request body?
Did you change the format of error responses?
Did you change HTTP status codes for existing scenarios?
Did you run an automated diff against the previous API spec?

If you answered yes to any of the first five questions, you have a breaking change. Decide whether to postpone it, version it, or communicate it clearly to all known consumers.

The Takeaway

Your API is a contract. Every consumer that depends on it has made an implicit agreement based on how it behaves today. Changing that contract without warning is not a technical mistake. It's a coordination failure that erodes trust across teams.

The goal is not to never make breaking changes. The goal is to know when you're making one, decide consciously whether it's worth it, and give your consumers a path forward. Automate the detection, communicate the change, and design for evolution from the start. Your consumers will never thank you for maintaining backward compatibility, but they will definitely notice when you don't.