Throughout our exploration of API Operations (APIOps), we've covered a range of concepts - from Continuous Integration and Deployment to API testing under stress. These pillars of APIOps have brought us invaluable insights, helping to streamline our workflows and ensure robustness and efficiency in our APIs. Our journey continues today as we introduce a new player into our existing pipeline - Tufin/oasdiff, a powerful tool that aids us in detecting changes in our API specifications.
API Diffing with Tufin/oasdiff
API diffing is the process of comparing two versions of an API to detect changes, additions, and removals. This is crucial for maintaining version control and ensuring backward compatibility. Tufin/oasdiff is an open-source tool designed to compare OpenAPI specifications (OAS) and highlight the differences. For this demonstration, we'll be utilizing Tufin/oasdiff in a Docker container, integrating it into our existing GitHub Actions pipeline.
Step 1: Incorporating Tufin/oasdiff into the Build Job
We're going to add a new step into our build job in the GitHub Actions workflow to run Tufin/oasdiff. This step will compare the current API definition with the previous one and report any differences.
1build:
2 runs-on: ubuntu-latest
3 steps:
4 - uses: actions/checkout@v2
5 - name: Install Vacuum CLI
6 run: npm install -g vacuum-cli
7 - name: Install Portman CLI
8 run: npm install -g portman
9 - name: Run Vacuum CLI for linting
10 run: vacuum validate ./path-to-your-api-spec-file.yaml
11 - name: Run Portman tests
12 run: portman --cliOptionsFile portman-cli-options.json
13 - name: API Diffing with Tufin/oasdiff
14 run: |
15 docker pull tufin/oas-diff
16 docker run -v ${PWD}:/data tufin/oas-diff old-api-spec.yaml new-api-spec.yaml
Step 2: Understanding the Output
Tufin/oasdiff provides a detailed report of the differences between two OpenAPI specifications. It categorizes changes into 'Breaking', 'Smooth', and 'Unknown'. 'Breaking' changes are those that cause incompatibility with the previous version, 'Smooth' changes are backward compatible, and 'Unknown' changes are those that may or may not be breaking. This output will help us decide whether to proceed with the deployment job or not.
Conclusion
APIOps is a multifaceted domain, and each component - be it Continuous Integration, Deployment, Load Testing, or API Diffing - plays a critical role in ensuring robust, efficient, and reliable APIs. The inclusion of Tufin/oasdiff in our pipeline underscores the importance of vigilance in tracking changes and maintaining compatibility. With every new tool and concept, we edge closer to mastering the art of API management. Onwards and upwards, API enthusiasts!
References
GitHub - codecentric/github-apiops-pipeline: An APIOps Pipeline for Github</>
Charge your APIs Volume 6: Perfecting Your APIOps - Harnessing the Power of k6 for API Testing</>
Was this post helpful?
More articles
fromDaniel Kocot
16.4.2024 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
Discover exciting further topics and let the codecentric world inspire you.
Gemeinsam bessere Projekte umsetzen.
Wir helfen deinem Unternehmen.
Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.
Hilf uns, noch besser zu werden.
Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.
Blog author
Daniel Kocot
Senior Solution Architect / Head of API Consulting
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.