Breaking changes
You can identify changes between different API versions reactively by running integration tests and seeing which features fail. However, that’s not the best way to identify what changed – or what will change – between two API versions. There’s a proactive approach you can follow even before you write any code. After you re-design your API and update your machine-readable definition document, you can compare it to the one from a previous version. Because the document is machine-readable, it’s easy to feed it to a tool that calculates the differences between both versions. This type of tool generates what we call an API diff.
API diffs are usually lists of differences between two JSON documents. Here’s an example output from oasdiff, a popular open source OpenAPI diff tool:
1 changes: 1 error, 0 warning, 0 info error[request-property-became-required] at payments.json in API POST /payments the request property 'cardCvv...
