Skip to content

Catch Breaking Changes with Seekret

Idan Gindi
By Idan Gindi
8 min read
API Observability
Catch Breaking Changes with Seekret

There’s no denying that API adoption for modern software development is skyrocketing and the recent surge in usage by companies around the world has drastically impacted the way APIs are handled and treated by developers now.

Previously, developers and engineering managers viewed the creation of an API as a one-time thing. You would build it, test it, then send it out to the world. It was never viewed as something that would mature along with development. Now, however, APIs are being productized because they provide countless opportunities for businesses to grow and expand. This resulted in a complete shift in the way R&D manages and maintains APIs. They are now viewed as a dynamic, growing product that evolves and requires continuous improvement over time. 

A big part of that evolvement comes from knowing how people use and consume your APIs through application behavior analysis. It comes from updating performance issues or adding additional functionality to the overall product capability. 

It can also come in the form of consumer feedback, updates made to partner APIs that require changes on your end, or feature enhancements. 

All of these use cases or reasons for changes to your APIs are good things! They help propel your business forward and provide real value to customers and integrators. They also reduce required development time and lower infrastructure costs when managed and maintained properly, all of which are strong KPIs for your team. 

Two questions always arise when thinking about this new methodology and how to advance your APIs through the SDLC:

  1. How will you handle these changes? 

  2. What will the strategy be for iterating, testing, documenting and releasing your APIs after they’ve been changed?

The old school method of advancing APIs through the SDLC 

Many times, the dev team that builds an API is not the same team that operates it. With that in mind, when answering questions 1 and 2, it’s important to take into consideration how multiple R&D teams are involved in accomplishing this task. Services are generally divided into respective teams so different developers are responsible for updating different APIs. Developers then need to somehow inform other dev teams of the changes they’ve implemented to make sure there are no breaking changes. Of course, things fall through the cracks and don’t get addressed or tested by QA - another department that’s involved. 

Breaking changes

So, different developers update different APIs, perhaps not in a cohesive and uniform way, then QA comes in and test the APIs, and finally, product, customer success, or another customer-facing department handles the API documentation to ensure it includes the recent updates, such as a change to the required status of a parameter or an addition to an endpoint’s response. 

While best practices showcase that joint ownership of APIs - specifically when they are owned by cross-functional teams - leads to enhanced API reliability and customer satisfaction, it only works when proper information is provided to every relevant stakeholder. 

Without an API management solution that incorporates observability into every step of the API development and iteration process, API owners and their departments will remain siloed and won’t be able to observe and manage all the API changes that take place within the CI/CD pipeline. 

The new API-first approach 

APIs were designed to simplify software development, but as the complexity of your APIs increase and as the number of their dependencies grow, you can’t expect to provide high performing APIs without a proper and insightful strategy that looks at every stage of the API iteration process. 

This is where API observability comes in. You can’t manage what you don't know and you can't secure what you don't see. With an observability solution, different development teams in your organization can collaborate on APIs and see changes other teams have implemented when pushing code. They can then understand the implications of those changes to the APIs they are responsible for and ensure that no breaking change occurred. 

Having a one-stop-shop for iterating, testing, documenting and learning about your APIs will not only give you the foundation for managing all the API changes that take place within the SDLC but it allows your teams to work faster and with clarity. 

This execution model explains how you can immediately catch breaking changes and ship APIs quickly using Seekret’s API observability solution.  

seekret PR graph

Open PR: Once you open a pull request, Seekret will run your test automatically and will capture every API update relevant for that code change. 

Inspect breaking changes: Drill down into every API change that took place across your test cases and see whether they are a breaking change or not. 

View affected dependencies & user flows: Correlate the detected API changes with affected consumers and your application’s behavior.

If you see that the API changes aren’t breaking changes, you can merge your PR at this stage. However, if they are breaking, you should update your code to handle this phenomenon. 

Fix code to prevent breaks: Update your code to ensure all dependent services and endpoints aren’t breaking as a result of the API change. 

Push changes: Push your most recent code so Seekret can rerun your tests automatically and capture the new changes. 

We suggest inspecting these changes and viewing their impact on relevant dependencies once more. If there are no breaking changes, you’re ready to merge! 

Leveraging API observability for build management 

The API-first approach to development undoubtedly has its benefits, and when you incorporate API observability as a layer within your API strategy, you ensure that your development teams have all the resources and insights they need to push code confidently. 

Here’s how easy it is to put this process in practice:

Step 1: Integrate observability with your CI/CD 

Seekret can be implemented locally or in production. Implementing Seekret into your CI/CD workflow is done by capturing requests using a proxy. Once you’ve implemented Seekret,  you can dive deeper into each change and understand the implications of that change to other services and relevant dependencies. 

Step 2: Inspect Breaking Changes 

Seekret instantly lists out every endpoint that’s been changed and provides insightful statistics. You can also drill down into each change per endpoint in order to truly understand the schema changes that took place. 

Here's what Seekret will catch:

Inventory

  • Added or removed endpoints from your overall API landscape

  • Number of endpoints that were changed

Schema

  • Change in parameter type

  • New or removed parameters

  • Required / unrequired parameter change

  • Response changes, including updates or additions/removals

  • Latency and metrics changes

Step 3: View Change Implications to Dependencies 

Now that you’ve automated the process of catching breaking changes, it’s time to analyze and understand the implications of those changes to your overall application. 

Seekret maps out the dependencies of every endpoint so when a change does occur, you can immediately understand whether its dependencies will be negatively affected. 

You can also check if the API change has impacted the journey a user would take in order to perform a specific function within your application. Seekret maps out all the user journeys that exist within your application and lists out all the journeys that include the updated endpoint. You can then view each and every user journey to understand how their experience will change based on the newly changed endpoint. 

What’s next? 

Now that we’ve answered how best to manage the constant stream of API changes that take place within your CI/CD, as well as how observability can assist in the iteration process, it’s time to:

  1. Fix code

  2. Finally merge to PR

  3. Test your application

  4. Update your documentation to reflect the changes made. 

Bug fixes

Observability plays a crucial role in this stage as well, and Seekret’s platform makes it easier than ever to automate API testing and documentation with observability. 

You can auto-generate and export API specs directly from the API inventory in your favorite format (Postman or OpenAPI) or you can enhance the auto-generated API spec with metadata and tags to create powerful and helpful API documentation. 

About Seekret 

Seekret's API governance framework empowers engineering teams with the observability they need to manage APIs, increase velocity, and reduce developer toil. Our API observability solution models APIs directly from traffic, bringing production knowledge to local API development practices, and provides clarity and insights on both user and application behavior.

Whether your organization has an on-premise infrastructure or you’re running on the public-cloud, Seekret’s API observability solution is the perfect tool for automating virtually every step of the API development process while ensuring governance to API builds and contracts. 

Want to learn more? Book a demo with us!