Skip to main content

Change your API with Optic

Optic gives teams tools to ensure every API change gets reviewed, approved, and documented, before getting released.

  • Do you know when your API changes?
  • How does your team talk about, consider and review possible API changes?
  • How do you make sure the API specification is updated when things change?

Talking about Change#

We have great tools for talking about code changes (Git, Line Diffs and PRs), but the tooling out here today does not make it easy to discuss API Changes. Instead of line diffs, of OpenAPI files, we need semantic diffs, detailing exactly what resources in our API have changed.

Like Git, Optic Specs include a history of every addition and change in your API since you ran api init. You can compare any two points in the history to understand how the API has changed.

The history page lists your documentation commits in chronological order, and lets you compare changes from any given point until the current documentation

Real API Changelogs#

Once you choose two versions of your API to compare, Optic's documentation viewer will render the changelog. We tried to build an experience similar to a Git compare page, but optimized for working with API changes.

Changes in your API are shown highlighted by endpoint

Endpoints are highlighted based on the type of change that has happened:

  • Green indicates endpoints that have been added are highlighted in green.
  • Yellow indicates changes have been made to an endpoint's shape.
  • Red endpoints have been deleted from the specification, and are no longer in the current version of the documentation.

Changes in your API are shown highlighted by endpoint

  • Green indicates a field that has been added in the history compare timeframe.
  • Yellow indicates changes have been made to a field, such as editing the field's type or metadata about the field (such as whether or not it is optional).
  • Red fields have been deleted from the specification, and are no longer in the current version of the documentation.

Discuss Change During Code Review#

Optic's ability to understand the changes to your API over time enable powerful workflows that fit nicely into Pull Requests. Our GitBot adds an accurate API Changelog to every Pull Request, giving teams the context they need to discuss API changes during code review.

"If we merge this PR, it changes this code, and updates that API endpoint"

The Optic GitHub Action will show what differences in behavior have been detected in your endpoints during CI tests


What's Next#