Microservices have now become the core part of any IT architecture, and that makes REST APIs an even more popular choice for developing any service. However, with the increase of API development, some challenges are also popping up which need attention. One of the biggest challenges is, while making enhancements to these APIs, developers may break the existing API features.
For example, let's suppose you have a REST API which pulls the order information of a customer by passing the parameter “orderid.” The parameter “orderid” can be optional. If it is not passed, it will return a list of all the orders for that customer. Now, this feature is running in Production without any issue. But, while doing an enhancement to some other API in the same code, the developer made this parameter “orderid” mandatory by mistake. This may break the existing consumers who are using the feature to get the list of all orders. Try to visualize having CI/CD in place; this change may even go to production, impacting the consumers.
Impact
It can impact the existing consumers heavily and make it difficult to revert back, as doing so will impact new consumers. In addition, doing blue-green deployment is impossible.
Solution Approaches
Approach 1
A unit test suite which does the API interface testing should fail, and that can alert for backward compatibility issues.
- Pros – Easy to write, as most applications already have a unit test part of the deliverable.
- Cons – The problem is that the developer can fix the unit test case as per the new API definition to get it through the build and test. It can easily be missed if the developer doesn’t pay attention.
Approach 2
An automated contract test suite plugged into your CI/CD pipeline can help to alert for backward compatibility failures.
- Pros – The QA team generally owns it, so it mitigates the risk of the developer ignoring it.
- Cons – This requires significant effort to write test automation scripts and plug them into the pipeline. You need to keep updating them with every enhancement. It is suitable only if your DevOps maturity level is 5 and contract testing is part of your planning already.
Approach 3
Versioning your REST API URL for every release and maintaining multiple versions of APIs until old customers move to new versions. That way, there is no need to worry about the backward compatibility.
- Pros – Versioning REST APIs is a good practice. It helps to track the changes better. Reverting the code also makes it easy.
- Cons – This is going to be messy if the application has frequent releases and you have to maintain many versions.
Approach 4
Checking backward compatibility through swagger-diff by plugging it into the CI/CD pipeline. swagger-diff provides utils and a CLI to compute the differences between two Swagger API specifications. The output of the differences can be put in a JSON or raw file. This output can be scanned and raise an alert to the team.
This approach is a bit new, but very flexible and effective. It requires minimal effort. So, let's explore this option in detail.
Features Provided by swagger-diff
swagger-diff defines rules that perform one type of diff checking. These rules are separated into two groups:
- Breaking change
- Smooth change
Breaking Changes
Examples:
- Delete path
- Rename path operationId
- Delete/Rename parameters
- Add a constraint on a parameter (like isRequired)
- Modify a response item
Smooth Changes
Examples:
- Add a path
- Add a param
- Add response item
- Add/Update descriptions
What You Will Build Here
Create a CI/CD pipeline job which will plug into swagger-diff to do backward compatibility checks of the REST API.
What You Will Need
- A CI/CD pipeline, e.g. Bamboo, gocd, etc… (I am using Bamboo for my example)
- Node.js
- npm
- bash script
- A REST API which has implemented Swagger API
P.S. Node.js, npm, and bash script are required on a CI/CD pipeline server.
Solution Details
swagger-diff implementation has been done through many languages. I have used a Node.js implementation (Refer to NodeJS-swagger-diff for more details).
A sample pipeline with a task has to be created. This task will have a shell script which can download and run the swagger-diff tool.
In the above code, there are three input parameters while running swagger-diff tool. These can be defined at the Plan Level in bamboo.
-
$bamboo_SWAGGER_API_URL_1
– This is the Production API URL (e.g. https://rest-service.apps.com/v2/api-docs) -
$bamboo_SWAGGER_API_URL_2
– This is the New API URL may be Dev Version (e.g. https://rest-service-new.apps.com/v2/api-docs) -
$bamboo_resultsfile
– This is the output file name which will contain the differences between the two APIs.
swagger-diff will compare the APIs and generate the results file in Artifact of the pipeline. Write a further script which scans the results, and if it finds anomalies or differences, it triggers the job to fail.
This can alert the team and they can check the results file in Artifact. The team can ensure if the differences are OK in the new API and appropriate measures are taken to address them and avoid an impact on existing customers.
Customize Rules for Output of the Differences
The output file generated by the pipeline task is in JSON format and it logs at 4 levels, as below:
- error – 3
- warning – 2
- info – 1
- ignore – 0
There is a configuration file which can be passed as a parameter while running the swagger-diff tool. This configuration file can be customized to show breaking and smooth changes as per your need.
I find this approach to be one effective way to identify backward compatibility for REST APIs. Share your experience through the comments if you know any alternate way to do it.
In our view, the best website analysis has three perspectives. First, it should ensure that the structural elements are in place and optimized for your keywords and objectives ingeniumcanada org
ReplyDeleteSo those with a clean genomic result might go for a cheap catastrophic plan, while those with a high risk of developing pricey illnesses will opt for more comprehensive Insurance.The result would be, in Insurance terms, an "adverse-selection death spiral," as the healthy opt out of expensive Insurance, the sick opt into it, and premiums spin out of control. What Is Swap In Insurance
ReplyDelete