Introduction
Every piece of software built in the 21st century uses APIs or is an API in itself. Because APIs are the fuel of digital transformation, 83% of IT businesses consider API to be critical to their business strategy in a recent report making API stability important.
Every API product starts small, and only exposes a few interfaces at the start. With time, it grows to hundreds (if not thousands) of APIs as new features are added. When an API becomes successful, it evolves with time, requiring frequent changes as businesses respond to changing markets and customer demands. With these frequent changes, comes the risk of introducing a disruption, in other words, breaking changes.
Analogize to Newton’s first law of motion for a body at rest. Likewise, if your API is static, you’re immune from the impact of breaking changes. Changes are what break APIs but they’re also inevitable and are difficult (if not impossible) to anticipate. Worse, in modern software companies, these changes occur often as new features are added and current ones are refined. For these companies, production releases occur every minute, increasing the danger of breaking their most valuable asset: APIs.
But if changes are inevitable, how do you ensure you don’t break your APIs when you make changes and evolve your existing APIs? What techniques and tools do successful firms use to continually deploy into production while keeping customers happy? In the post, you will learn how to ensure you’re not breaking your APIs.
The Consequences Of An API Breaking Change
We established earlier that your APIs will evolve over time, whether it's due to changing business goals or new initiatives. When this change isn't adequately handled, it becomes a game-changer with significant implications for the company and its customers. Below are the reasons you should avoid breaking changes.
Bad for customer experience
A positive customer experience is beneficial not only to your users but also to your business, as it boosts customer lifetime value (CLV). To provide a great customer experience, you have to make sure your API is consistent and frictionless for the consumers or users. Each time a breaking change is introduced, existing consumers of the API would either have to adjust their code or re-integrate, which leaves a bad experience.
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. Earlier adopters leave negative reviews, which can be extremely damaging to a business and make acquisitions of new users difficult.
Costly on both the provider and the consumer
Remedying the impact of breaking change is time-consuming and costly. As an API provider, you have just two options when you break your API. You could create a new API without the breaking change. However, developing a new API requires development effort. Furthermore, you’ll also have two APIs to maintain simultaneously and cost borne into the future. As for the second option, you could locate all of the API dependencies, find where the problem is and resolve them. Without considering the time factor here, locating all API dependencies is expensive and impossible at worst. An API used by thousands of developers across the globe would be impossible to track down and resolve.
What Constitutes A Breaking Change?
Your change is breaking if the modification to your API has the potential to break a client's application. Breaking changes usually entail altering or removing existing API components.
Existing API clients may or may not be broken by merely adding to an API, but any deletion changes to an existing API are breaking changes. Applications dependent on the API may stop running if they attempt consume the deleted resource, field, or structure. A breaking change can have a variety of effects, ranging from a minor cosmetic effect to rendering a program utterly unusable.
Your change is broken if it:
Involves modification of existing contracts (interfaces): Changes to an existing contract range from adding a new property, to removing or renaming a property.
Involves modification to API data payload: APIs receive requests and return responses. The changes to the shape of data, either in the request or response object constitute a breaking change.
Changes to quantitative metrics of the API endpoint may constitute a breaking change: An increase in API endpoint latency after a new change may break existing customers who need extremely low latency to function.
Why Do We Break APIs?
API breaking is nearly never done on purpose. They're the outcome of ongoing efforts to improve or evolve a product in response to new needs, such as:
Supporting new features: Providing support for new features in your API such as required query parameters or mandated security schemes could cause an API to break.
Simplifying the APIs: In light of new discoveries and learnings from customers, engineers and businesses may improve existing API design by simplifying the flow or removing logic that no longer holds true which leads to the introduction of breaking change.
Improving maintainability: Attempt to evolve an API more flexible and maintainable into the foreseeable future may lead to breaking changes.
How To Prevent Breaking Changes
Because making changes to API are necessary, it’s important that these changes are introduced without impacting existing customers. To do this, you have to follow a number of practices to introduce while introducing your change.
Future-proof documentation: While it may sound corny, but documentation may well assist you to prevent breaking changes, particularly additive ones. Some objects, for example, may consist of only a few fields in the early phases of a platform. If you know that a lot more fields will be introduced in the future, you may tell your consumers to expect it and plan accordingly.
Test for accidental breaking changes: Breaking changes are especially difficult to deal with if you aren't aware of them. Thankfully, you can leverage different automation to make you aware of breaking changes in your CI/CD pipeline. Openapi-diff is one solution that assists in evaluating two OpenAPI - v3 specifications and notifies you if there have been any evident breaking changes.
Plan API in advance: It may seem self-evident, but the significance of carefully structuring your APIs cannot be overstated. It can be tempting to roll out small changes fast without following due process. With time, breaking changes can slip by with no one noticing. If your API is properly planned, even something as simple as naming might result in breaking updates or a consistently terrible development experience.
Use deprecation header: You can deprecate features before completely eliminating or altering them to give consumers of your API just a little bit more time to respond. This information should be included in the deprecation HTTP header field. This is the case when the only alternative is to make a significant change that will cause a break.
Set clear timeline: Set explicit deadlines for when new versions will be released and when old versions will no longer be supported to avoid causing uncertainty and encouraging action. When crucial deadlines approach, you can still allow some wiggle room.
API Observability: API Observability evolves from traditional monitoring and is based on the principle of control theory which is the ability to understand a system by looking at its external output. API observability allows you to see what changes were made by all of your R&D developers in one place, and it allows you to test those changes with greater clarity and insight. Both of these things combined to ensure that the APIs are not only reliable and always work, but they are also delivered quickly because so much time was saved using this process.
Conclusion
Every business has a mandate to keep its APIs stable and running to continuously deliver values to existing consumers without disruptions. To respond to the rapidly changing competitive landscape as new learnings are unraveled, businesses are also tasked with adapting and re-inventing existing APIs. In this post, we’ve touched down on ways to evolve your APIs without impacting consumers in a huge way…. CTA
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.
Breaking changes don’t impact external consumers of an API, but also internal consumers. Even if you do not make your API available to external users, there is a tendency for that API to be used by teams within your organization. This is why API observability is a must-have for every software company.
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 the consumer. This is why it's crucial to bake observability into your API from the very beginning.
Should talk about how breaking changes don't just impact external APIs and consumers but also internal ones and that API observability gives you what you need to manage both internal and external perfectly.