OpenAPI Diff Prevents API Breakages
Written by Nikos Vaggalis   
Tuesday, 25 July 2023

OpenAPI Diff, or Oasdiff for short, is an open source utility that takes comparing OpenAPI specs to identify breaking changes to a whole new level.

The consensus is that despite have a multitude of tools available nowadays, designing and maintaining an API is still not an easy task to perform. One of the aspects that causes problems is the dreaded "breaking change". Why is that? Let Oasdiff main implementer and Tufin CTO, Reuven Harrison, explain:

  • What is a breaking change?
    A breaking change is a change to a component, such as a server, that could break a dependent component, such as a client, for example deleting an endpoint. When working with OpenAPI, breaking-changes can be caught by monitoring changes to the specification.
  • Why check for Breaking Changes?
    Detecting breaking changes in OpenAPI is an effective way to avoid downtime and maintain business-continuity, especially for complex applications that involve many APIs, multiple services, large or distributed development teams or undergo frequent changes.

A diff tool can be used to track changes made by developers to APIs, understand their context and impact, provide documentation for API consumers who want to track functionality changes including bug fixes and upgrade paths, and most importantly, to detect breaking-changes and even prevent them.

OpenAPI Diff is a tool that can make that task easy to perform, offering a Java library, a CLI utility, even an online playground for manual comparison, as well as a webservice which you can Curl. It also integrates with the CI/CD pipeline, hence catering for every need and environment out there.

This last part on the CI/CD pipeline is and the most important since automated checking that can detect non-trivial breaking-changes can help to prevent downtime. As such, users can run oasdiff in their CI/CD pipeline as a docker image or a cmd-line to test for breaking-changes and/or break the build on certain conditions. For Github specifically there is also a GitHub action.

The tool's main features are :

  • Detecting breaking changes
  • OpenAPI diff in YAML, JSON, Text/Markdown or HTML
  • Display a user-friendly changelog of all important API changes
  • Run from Docker
  • Embed in your go program
  • OpenAPI diff of local files system or remote files over http/s
  • Compare specs in YAML or JSON format
  • Compare two collections of specs
  • Comprehensive diff including all aspects of OpenAPI Specification: paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
  • API deprecation
  • Path prefix modification
  • Path parameter renaming
  • Excluding certain kinds of changes
  • Excluding endpoints
  • Extending breaking-changes with custom checks
  • Localization

oasdiff

Additional improvements in oasdiff’s newest version's breaking-changes:

  • human readable output
  • supports localization for error messages and ignored changes
  • checks can be modified by developers using oasdiff as a library with their own specific checks by adding/removing checks from the slice of checks
  • ability to ignore certain changes with a configuration file
  • support for stability-levels which allows breaking-changes in early development phases like draft and alpha but not later in beta and stable
  • fewer false-positive errors by design
  • improved support for type changes: allows changing integer->number for json/xml properties, allows changing parameters (e. g. query/header/path) to type string from number/integer/etc.
  • allows removal of responses with non-success codes (e. g. , 503, 504, 403)
  • allows adding new content-type to request
  • easier to extend and customize

The tool's many faces:

1. Available on Maven Central as a library:

<dependency>
<groupId>org. openapitools.openapidiff</groupId>
<artifactId>openapi-diff-core</artifactId>
<version>${openapi-diff-version}</version>
</dependency>

2. Available on Docker Hub as tufin/oasdiff.

3. Available as a Webservice

# download the base spec
curl -o openapi-test1.yaml https://raw.githubusercontent. com/
                 Tufin/oasdiff/main/data/openapi-test1. yaml

# download the revised spec
curl -o openapi-test3.yaml https://raw.githubusercontent. com/
                         Tufin/oasdiff/main/data/openapi-test3. yaml

# check breaking changes by using the web service
curl -X POST \
-F base=@openapi-test1.yaml \
-F revision=@openapi-test3.yaml \
https://api.oasdiff.com/breaking-changes

4. Available as an online playground Diff Calculator.

One last thing though. How does it compare to the official OpenApi diff utility? Here's a detailed comparison chart that highlights the differences:

oasdiff 

OpenAPITools/openapi-diff

Stack 

golang 

Java

Docker image size 

< 7 MB 

> 80 MB

Diff 

Deep and comprehensive. Catches every kind of change.

Shallow and partial. 

Ignores some kinds of  

changes.

Diff files from local file  

system

Yes 

Yes

Diff remote files from http 

Yes 

No

Output 

json 

yaml 

text 

markdown 

html

json 

text 

markdown 

html

Colorized Output 

Yes 

No

Diff between multiple specs  (using globs)

Yes 

No

Breaking Changes 

Full with > 100 checks. 

Specifies exact breaking  changes in human-readable  language.

Partial (# of checks  

unknown). 

Only tells you whether there  were any breaking changes,  doesn't specify the exact  breaking-changes.

Deprecation policies 

Yes 

No

Ignore Specific Breaking  Changes with Configuration

Yes 

No

Localization 

Yes 

No

In conclusion, Oasdiff's approach to preventing breaking changes is a solid attempt to help in designing and maintaining APIs, as such earning itself a place in the developers' arsenal of most valuable tools.

 oasdiffsqu

 

More Information

OpenAPI Diff Home 

Github

Related Articles

Learn To Protect Your APIs By Hacking Them

 

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Banner


Python 3.13 Is Here
09/10/2024

As time ticks on, the changes to the Python language become fewer and this makes it easier to upgrade. With this release the emphasis is on performance rather than new features.



Mojo - Python Superset For Go-Faster Hardware
07/10/2024

Mojo, the new language from Chris Lattner and his AI-focused company Modular, has entered the top 50 of the TIOBE index, even though it it was only launched in 2023.


More News

espbook

 

Comments




or email your comment to: comments@i-programmer.info

Last Updated ( Tuesday, 25 July 2023 )