Check for Breaking Changes

3 minutes

Don't break your consumers, catch breaking changes early! Optic makes it easy for every developer to understand if they've proposed breaking API changes before they are released. Breaking change checks helps your team keep its promises to consumers.

Detecting breaking changes

Optic can lint your API design, OpenAPI document and the changes between versions. Optic ships with built-in rules that check the changes between each version for breaking changes. Breaking change checks are enabled by adding --check flag to optic diff:

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

Read full documentation for optic diff

Visualizing Breaking Changes

For a more detailed view of breaking API changes, you can include the --web flag. This computes the changelog locally and includes it via a URL to Optic's visual changelog view (we do not save the data).

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

openapi.yaml

openapi: 3.0.1

paths:
 /todos:
  get:

   parameters:
    - name: limit
      in: query
      schema: 
       type: number
      required: true 

   responses:
    '200':
      content:
       application/json:
        schema:
        type: object
        properties:
         todos:
         type: array
         items:
          $ref: "#/components/schemas/TodoRead"

components:
 schemas:
  TodoRead:
   type: object
   properties:
     name:
       type: string

     status:
       type: string

     status:
       type: number

     tags:
       type: array
       items:
        type: string

     created_at:
       type: string
   required:
     - name
     - status
     - created_at

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. Learn more here