---
title: "How to Prevent Breaking API Changes with API Gateway - API7.ai"
description: "This article explores the best practices to handle API-breaking changes with API Gateway."
url: "https://api7.ai/blog/detect-breaking-api-changes"
---

[Blog](https://api7.ai/blog)

[Products](https://api7.ai/category/products)[Technology](https://api7.ai/category/technology)[Ecosystem](https://api7.ai/category/ecosystem)[Case Study](https://api7.ai/category/usercase)[Team & Community](https://api7.ai/category/community)

Search

⌘ + K

[Blog](https://api7.ai/blog)

Technology

# How to Prevent Breaking API Changes with API Gateway

[![Bobur Umurzokov](https://avatars.githubusercontent.com/u/14247607)](https://www.linkedin.com/in/boburumurzokov/)

[Bobur Umurzokov](https://www.linkedin.com/in/boburumurzokov/)

September 11, 2023

[Technology](https://api7.ai/category/technology)

When you develop APIs, you sometimes change things that might cause problems for current API consumers. [Evolving your API](https://blog.frankel.ch/evolve-apis/) 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](https://apisix.apache.org/) 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:

1. **Removing an Endpoint**: If you have a `GET /users` endpoint and decide to remove it, any client trying to access it will receive errors.
2. **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.
3. **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.
4. **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" }`.
5. **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`.
6. **Changing Authentication Mechanisms**: If you switch from basic authentication to token-based authentication without proper transition, existing clients will face authentication errors.
7. **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.
8. **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.
9. **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.
10. **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](https://apisix.apache.org/docs/apisix/plugins/request-validation/) plugin to validate incoming requests and the [response-rewrite](https://apisix.apache.org/docs/apisix/plugins/response-rewrite/) plugin to rewrite the API response based on certain conditions.

### Logging

APISIX supports various logging plugins, such as [http-logger](https://apisix.apache.org/docs/apisix/plugins/http-logger/), [elasticsearch-logger](https://apisix.apache.org/docs/apisix/plugins/elasticsearch-logger/), [file-logger](https://apisix.apache.org/docs/apisix/plugins/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](https://api7.ai/blog/api-health-with-prometheus-apisix) 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](https://prometheus.io/) using the [prometheus](https://docs.api7.ai/apisix/how-to-guide/observability/monitor-apisix-with-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](https://apisix.apache.org/docs/apisix/tutorials/add-multiple-api-versions/) 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](https://apisix.apache.org/docs/apisix/plugins/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](https://apisix.apache.org/docs/apisix/plugins/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](https://www.openapis.org/) 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](https://www.oasdiff.com/) or [Bump](https://bump.sh/api-change-management) can identify changes in API specs, and trigger a CI pipeline (add [GitHub Action](https://docs.github.com/en/actions)) that runs tests against the route endpoints in APISIX to ensure no breaking changes are introduced.

![api-breaking-changes-detector-git](https://static.api7.ai/uploads/2024/12/25/V3AsVrJp_api-reaking-changes.png?imageMogr2/format/webp)

### Other ways of detecting changes

[Postman](https://www.postman.com/) contains a [template](https://explore.postman.com/templates/13892/breaking-change-detector) to automatically check the current version of your API for breaking changes and describes how it works in this [article](https://blog.postman.com/how-to-catch-breaking-changes-before-they-happen/). 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](https://navendu.me/posts/api-deployment-strategies/) explains well how to catch them in practice using tested deployment strategies before taking new changes to production.

## Summary

Detecting and preventing 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.

## Related resources

[Keep up APIs healthy with APISIX and Prometheus](https://api7.ai/blog/api-health-with-prometheus-apisix)

[Request validation in API Gateway](https://youtu.be/_O-gg1VLQxU?si=gqGTdk8Qw4I-rPrL)

Tags:

[API Gateway](https://api7.ai/tags/api-gateway)

[API breaking changes](https://api7.ai/tags/api-breaking-changes)

[Detect API changes](https://api7.ai/tags/detect-api-changes)

[Backward-compatible](https://api7.ai/tags/backward-compatible)

Share article link

Share

Related Posts

[![Bot Traffic Moves: Build API Defenses That Follow Behavior](https://static.api7.ai/uploads/2026/10/20/TEFXEwQQ_bot-traffic-migration-api-gateway.webp)](https://api7.ai/blog/bot-traffic-migration-api-gateway)

## [Bot Traffic Moves: Build API Defenses That Follow Behavior](https://api7.ai/blog/bot-traffic-migration-api-gateway)

[![HTTP Connection Reuse: The Hidden API Latency Multiplier](https://static.api7.ai/uploads/2026/10/20/ChYoK0yi_http-connection-reuse-api-gateway-latency.webp)](https://api7.ai/blog/http-connection-reuse-api-gateway-latency)

## [HTTP Connection Reuse: The Hidden API Latency Multiplier](https://api7.ai/blog/http-connection-reuse-api-gateway-latency)

Table of Contents

- [What are API-breaking changes?](#what-are-api-breaking-changes)

  - [Request & response schema validation](#request--response-schema-validation)
  - [Logging](#logging)
  - [Route and upstream monitoring](#route-and-upstream-monitoring)
  - [Use versioning](#use-versioning)
  - [Deprecation notices](#deprecation-notices)
  - [Integration with version control](#integration-with-version-control)
  - [Other ways of detecting changes](#other-ways-of-detecting-changes)

- [Summary](#summary)

- [Related resources](#related-resources)

## Related Posts

[![Partial API Outages Need Retry Budgets, Not Retry Storms](https://static.api7.ai/uploads/2026/11/10/Upkbmn88_api-retry-budgets-partial-outages.webp)](https://api7.ai/blog/api-retry-budgets-partial-outages)

Technology

November 10, 2026

#### [Partial API Outages Need Retry Budgets, Not Retry Storms](https://api7.ai/blog/api-retry-budgets-partial-outages)

Use failure phase, idempotency, deadlines, backoff, and one retry owner to recover from partial API outages without multiplying load or side effects.

[API Reliability](https://api7.ai/tags/api-reliability)

[API Gateway](https://api7.ai/tags/api-gateway)

[Retry](https://api7.ai/tags/retry)

[![Incremental API Gateway Configuration: Rebuild Less, Verify More](https://static.api7.ai/uploads/2026/11/03/5tHRA5Tn_incremental-api-gateway-configuration.webp)](https://api7.ai/blog/incremental-api-gateway-configuration)

Technology

November 3, 2026

#### [Incremental API Gateway Configuration: Rebuild Less, Verify More](https://api7.ai/blog/incremental-api-gateway-configuration)

Apply targeted-build lessons to API gateway configuration: classify changes, combine work, retain full reconciliation, and prove equivalent output.

[API Gateway](https://api7.ai/tags/api-gateway)

[Platform Engineering](https://api7.ai/tags/platform-engineering)

[GitOps](https://api7.ai/tags/gitops)

[![Internal APIs Are Production Security Boundaries](https://static.api7.ai/uploads/2026/11/03/kXDv6D2O_internal-api-security-boundaries.webp)](https://api7.ai/blog/internal-api-security-boundaries)

Technology

November 3, 2026

#### [Internal APIs Are Production Security Boundaries](https://api7.ai/blog/internal-api-security-boundaries)

Use a current internal-tool incident to design identity, authorization, traffic, and audit controls that limit blast radius without overstating gateway protection.

[API Security](https://api7.ai/tags/api-security)

[Internal APIs](https://api7.ai/tags/internal-apis)

[Zero Trust](https://api7.ai/tags/zero-trust)
