Skip to main content

Tutorial: Catch Breaking Changes

This is a quick tutorial that shows you how to catch breaking changes with Optic

1. Install the Optic CLI

npm install -g @useoptic/optic

2. Clone the demo repo

git clone https://github.com/opticdev/openapi-demo
cd openapi-demo

3. Use the diff command to compare the two versions of the OpenAPI specification.

optic diff todo-api.yaml todo-api-breaking-change.yaml

In this example there are two changes between the versions:

  • We made status a number instead of a string
  • We have renamed name to message.
GET /todos:
  - response 200:
    - body application/json:
      - field message added
      - field name removed
      - field status
        - schema changed

Both of these changes are breaking. Let's see if Optic can catch them.

4. Now let's run the diff with the --check flag:

optic diff todo-api.yaml todo-api-breaking-change.yaml --check
Checks

   FAIL  GET /todos
    Rule: prevent removing response property
    x removed property name
      removing a required response property is a breaking change
      at /todo-api.yaml:33:673

    Rule: prevent response property type changes
    x changed type of property status
      changing the type of a response property is a breaking change
      at /todo-api-breaking-change.yaml:35:713



3 changes detected
1 checks passed
2 checks failed

Optic found two breaking changes:

  • the first is from renaming name to message. Adding message is not breaking, but removing name could break clients who were using that property.
  • the second is changing status from a string -> number. This will break clients that parse that property as a string.

If we include the --web flag Optic will visualize the API diff and issues:

alt

5. Try it yourself!

Run breaking change checks on your own OpenAPI files

  1. Create a branch
  2. Make a breaking change (e.g. removing a property, making an optional parameter required, removing an operation)
  3. Run breaking change checks between your current branch and the default branch
optic diff specs/service-api.yaml --base main --check

Using Optic as you write OpenAPI​

Optic can help you understand if any of the changes you're proposing to the API are breaking. The tool is built to work alongside Git to make it easy to compare OpenAPI versions across branches.

optic diff openapi.yaml --base main --check

base is the branch you want to compare against, usually if you are working on feature branches it will be the name of your default branch.

Catch Breaking Changes in CI

You can set up Optic Cloud to catch breaking changes in CI. Optic can be set up to fail CI on Pull Requests that introduce known breaking changes to consumers. Get started here