Our great sponsors
-
-
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
-
-
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
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.
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.
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.
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.
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.