Skip to content

How to Avoid Breaking Changes When Upgrading Your APIs

Val Pliskin
By Val Pliskin
8 min read
API Observability
How to Avoid Breaking Changes When Upgrading Your APIs

Every piece of software built in the 21st century uses APIs or is an API in itself. APIs are the fuel of digital transformation, leading one 2020 report to find that 83% of IT businesses consider their API to be critical to their business strategy. Having a stable API is thus equally important. 

Every API product starts small, exposing only a few interfaces. As new features are added, it grows to hundreds (if not thousands) of APIs. A successful API evolves over time, requiring new features as your business responds to changing markets and customer demands. But with these frequent changes comes the risk of introducing a disruption or breaking change.

If your API remains static, it will be immune to the impacts of breaking changes. But change is inevitable and can be difficult (if not impossible) to anticipate. In modern software companies, changes occur to an existing API to refine and upgrade it per user needs, production releases that can occur every minute for some companies. So ensuring they don't break your existing API is essential.

What techniques and tools do successful organizations use to continually deploy to production and improve their interface without any breaking changes? In this post, we’ll learn how to successfully upgrade your API while keeping your customers happy.

The Consequences of a Breaking Change in APIs

As mentioned, every API will evolve over time due to changing business goals or new initiatives. But when changes aren't handled properly, there can be significant negative implications for the API provider and its users, some of which we discuss below. 

breaking change impact

High Cost

Remedying the impact of a breaking change is time-consuming and costly—for both the provider and consumer. As an API provider, you have only two options when you break your API. You can develop an entirely new API, which requires significant development effort and leads to the cost of having to maintain two APIs simultaneously going forward. 

The second option is to locate all of the API dependencies, find the issue, and resolve it. Besides the time required to do this, locating all API dependencies is expensive and, at worst, impossible. Morden software companies have product teams that focus on specific business domains. These teams often leverage internal APIs from other teams to build their products. So when an API is updated, engineers need to find the teams using the API and make sure they are aware of the changes made.

Slow Adoption

One of the major drivers of API adoption is simplicity and consistency. APIs that consistently violate backward compatibility suffer reputational damage, resulting in a low adoption rate.   

If you choose to continuously deprecate older APIs that are broken, instead of fixing them, you will face serious difficulty in acquiring new users. Nobody wants to have to re-update their framework each time you make a breaking change. 

Negative User Experience

A positive customer experience is beneficial not only to users but also to your business, as it boosts customer lifetime value (CLV). To provide a great user experience, you have to make sure your API is consistent and frictionless. As noted above, breaking changes mean  consumers of your API have to adjust their code or re-integrate, which leads to a negative experience. Moreover, every breaking change requires extra documentation from both the API provider and API users reporting the new change.

negative / positive experience

What Constitutes a Breaking Change?

A breaking change occurs when a modification to an API has the potential to break a consumer’s  application or the API. Breaking changes usually entail altering or removing existing API components. Merely adding to an existing API may not lead to a break. However, any deletion constitutes a breaking change if the deleted resource is utilized downstream, as applications dependent on the API may stop running if they consume the deleted resource, field, or structure. 

Breaking changes can have a variety of effects, ranging from a minor cosmetic impact to rendering a program unusable. 

A change is breaking if it:

  • Involves a modification to quantitative metrics of the API endpoint: One example of this is an increase in API endpoint latency after a change, leading to poor user experiences and prompting customers to switch to a new provider, or a new response code that breaks a user’s flow. 

  • Involves a modification of an existing contract or schema: Changes to an existing contract include adding, removing, or renaming a parameter.

  • Involves a modification to an API data payload: APIs receive requests and return responses, and any changes to the shape of data either in the request or response object can become a breaking change. 

Why Do We Break APIs?

You typically never break an API on purpose. It is an unintended consequence  of continuous efforts to improve or evolve a product in response to new needs, such as:

  • Support for new features: Supporting new features in your API such as required query parameters or mandated security schemes can cause an API to break.

  • A simplified API:  Simplifying the flow of your API or removing logic that no longer holds true can lead to the introduction of a breaking change.

  • Improved maintainability: Upgrading your API to make it more flexible and more maintainable into the foreseeable future can lead to breaking changes.


Leveraging Observability to Prevent Breaking Changes

Making changes to your API is necessary, but it’s important that these changes are introduced without impacting existing customers. To do this, you first must implement API observability, which then enables a number of practices to ensure the stability of your API during an upgrade.

API observability evolves from traditional monitoring and is based on the principle of control theory—the ability to understand a system by looking at its external output. API observability enables you to see what changes were made by all of your developers in one place and lets you test those changes with greater clarity and insight. This, in turn, ensures that your APIs are not only reliable but are also delivered quickly (due to the time saved using this process).

An additional benefit of API observability is that your teams can see how their APIs are being used and driving business value. Also, documentation is essential to prevent breaking changes, particularly additive ones. But you can only keep documentation up to date if you have visibility into what changes were made and where. API observability gives you this, enabling proper documentation for the benefit of both internal and external consumers of your API. Furthermore, observability improves your documentation since it lets you know what to update as well.

Once you achieve observability, there are a number of steps you can take to further prevent breaking changes, discussed here below.

Test for Accidental Breaking Changes

Breaking changes are especially difficult to deal with if no one is aware of them. Thankfully, you can leverage automation to be aware of such changes in your CI/CD pipelines. Seekret is one solution that assists in evaluating your API and catching  breaking changes in CI/CD before they are released to customers. 

Plan Your API in Advance

It may seem self-evident, but the significance of carefully structuring and planning APIs cannot be overstated. It can be tempting to roll out small changes fast without following due process, but over time, this leads to breaking changes slipping by unnoticed. If an API is not properly planned, even something as simple as naming might result in a breaking change.

plan APIs

Use the Deprecation Header  

With the deprecation header, you can deprecate features before completely eliminating or altering them to give consumers of the API just a little bit more time to respond. This information should be included in the deprecation HTTP header field and can be helpful when the only alternative is to make a significant change that will cause a break.


Every business has a mandate to keep its APIs stable and running to continuously deliver value to existing consumers without any disruption. However, in response to the rapidly changing competitive landscape, businesses are also tasked with adapting and re-inventing existing APIs.

API observability lets you see in advance—and therefore reduce—the potential impact of upgrades, meaning you can evolve your APIs without breaking anything for consumers. It’s important to remember that breaking changes not only impact external consumers of an API, but also internal ones. And even if you do not make your API available to external parties, it may still be used by teams within your organization. This is why it's crucial to bake observability into your API from the very beginning. 

About Seekret 

Seekret’s API observability platform lays the foundation for developer productivity and API management, allowing engineering managers to release reliable and consistent APIs with lightning speed.

If you'd like to see these features in action, feel free to book a demo!