When you develop APIs, you sometimes change things that might cause problems for current API consumers. Evolving your API product without affecting current users is essential, otherwise, they might lose trust in your offer. It’s impossible to altogether avoid these problems but you can minimize the impact or catch some catch-breaking changes before they happen. Breaking changes need to be identified during the development phase, and if they happen, the API gateway should handle them to ensure client applications remain unaffected. In this article, we will explore some best practices and strategies to prevent API-breaking changes and how to handle them using the APISIX API Gateway.

What are API-breaking changes?

Software products evolve consistently, and their APIs are no exception. These APIs serve as the primary interface through which external API consumers engage with your system, mirroring any product changes. There are various reasons for these API modifications, including technological improvement, shifts in business direction, critical bug resolutions, and more. In simple terms, a breaking change is when you change your API and it might cause problems for client apps using it. Some of these changes are easier to spot than others. Here are some examples of breaking changes:

Removing an Endpoint: If you have a GET /users endpoint and decide to remove it, any client trying to access it will receive errors.
Changing the URL of an Endpoint: If you change the URL of an endpoint from GET /users to GET /members, any client using the old URL will face issues.
Modifying the Request Payload: If an endpoint expects specific data in the request, like POST /users expecting { "name": "John" }, but you change the requirement to { "firstName": "John" }, it will disrupt the clients sending the old format.
Removing or Renaming Fields in the Response: If clients expect specific fields in the API response, removing or renaming them will cause those clients to malfunction. For example, they are changing { "id": 1, "name": "John" } to { "id": 1, "fullName": "John Doe" }.
Changing Data Types: If an API field is expected to be a string and you change it to an integer or another type, this can break clients. For instance, varying "age": "25" to "age": 25.
Changing Authentication Mechanisms: If you switch from basic authentication to token-based authentication without proper transition, existing clients will face authentication errors.
Introducing Mandatory Fields: If you have an endpoint like POST /users that takes optional fields, and you suddenly make one of those fields mandatory, existing clients not sending that field will face issues.
Changing Error Formats: If clients are programmed to understand specific error formats, changing those formats can lead to improper error handling on the client side.
Modifying HTTP Status Codes: Changing the status codes for certain operations, like returning a 200 OK instead of a 201 Created for resource creation, can mislead clients.
Deprecating Support for Older API Versions: If you phase out support for older versions without a proper transition period, clients relying on those older versions will break.

Every change in API has the potential to break a client application. If you use API Gateway like a front door for all the backend APIs, the gateway knows where to forward the request based on a set of rules defined in a route configuration and it is the right place to handle breaking API changes. Let’s see how we can use APISIX to identify some API changes

Request & response schema validation

Defining strict schemas for your routes allows you to ensure request and response structures are as expected. Use the request-validation plugin to validate incoming requests and the response-rewrite plugin to rewrite the API response based on certain conditions.

Logging

APISIX supports various logging plugins, such as http-logger, elasticsearch-logger, file-logger, and more. Set up a logger to store the API request and response data and analyze logs regularly to detect changes in request/response headers, payload structures, or any other unusual patterns.

Route and upstream monitoring

Monitor the routes passing through the gateway. If a previously available route suddenly starts returning 404 errors, it’s a potential sign that the API has undergone a change or an endpoint has been deprecated. Enable the API health check feature to monitor continuously the overall health of upstream nodes. If one of the nodes starts to fail, responding faster or slower than usual, it might indicate a change in the underlying backend service’s processing. Integrate APISIX with monitoring tools like Prometheus using the prometheus plugin. Set up alerts based on metrics, such as an increased rate of 4xx or 5xx errors, which could indicate breaking changes in your API.

Use versioning

API versioning is the practice of managing changes to an API and ensuring that these changes are made without disrupting API consumer apps. There are various methods to set up versioning with APISIX, like using URI paths, query parameters, headers, or picking the content type. For instance, you might have web addresses like /v1/users or/v2/users to show your API's version. By having these versions, you can offer more than one option of your API, API consumers to decide when to upgrade to the latest version at their own pace. APISIX can easily redirect all traffic back to the old, stable version of the API until you address the issues in the new version that makes your APIs backward-compatible. Employ APISIX to retain the old compatibility while rolling out the new changes if you detect issues in the new version, the traffic-split plugin allows for a quick rollback.

Deprecation Notices

Before removing or altering features, mark them as deprecated, giving consumers adequate time to adapt. With the help of the APISIX, we can configure the route to communicate about its future deprecation and its replacement. For that, APISIX offers the response-rewrite.

Integration with version control

While you might wish that pull request reviewers would spot any breaking changes, relying solely on this method is not certain and might lead to failure eventually. If you have OpenAPI/Swagger documentation for your APIs, these can be version-controlled and included in a CI pipeline. APISIX doesn’t natively support direct integration with version control systems like Git for API specification changes. However, you can set up a process outside APISIX. Tools like Oasdiff or Bump can identify changes in API specs, and trigger a CI pipeline (add GitHub Action) that runs tests against the route endpoints in APISIX to ensure no breaking changes are introduced.

Other ways of detecting changes

Postman contains a template to automatically check the current version of your API for breaking changes and describes how it works in this article. You add the detector to the CI pipeline as an extra step. Every time your pipeline executes, the breaking change detector will analyze the present API spec against the previous one and notify you of any differences. Depending on your development stack, there are other libraries to compare OpenAPI specifications. This article explains well how to catch them in practice using tested deployment strategies before taking new changes to production.

Summary

Detecting breaking API changes is important for maintaining trust with API consumers and ensuring the success of your service. By integrating APISIX’s capabilities like request validation, versioning, logging, monitoring, and alerting with techniques like automated API contract testing, you can ensure your APIs evolve without negatively affecting your clients.

Keep up APIs healthy with APISIX and Prometheus

Request validation in API Gateway