How It Works

The most important moments in the lifecycle of an API are the times when it changes. At its core, Optic helps teams manage changes to your APIs. When every API change is tracked, documented, and reviewed — teams ship better APIs.

Optic is designed to fit into your CI pipeline which ensures we can track every change, keep your documentation in sync and automatically check for breaking changes.

1. Upload

Optic tracks changes to your APIs. To get started, your team uploads an initial OpenAPI spec. Optic works with whatever your team’s development process is. Optic supports OpenAPI was written by your team or generated at build time.

Most teams upload their OpenAPI spec as part of continuous integration on every commit. Optic includes integration documentation for all of the major CI platforms so that it’s as easy as possible to set up. There’s even a GitHub Action.

$ optic spec push spec.yml

For teams with unique workflows, Optic includes a CLI that can be used to script the upload no matter the scenario.

Don’t have an OpenAPI spec yet? Don’t worry. Our team would love to help you create one.

2. Analyze

When new specs are uploaded, Optic compares it to your API’s current behavior. If it’s the first spec for an API, Optic sets the baseline for the API. If it’s an updated spec, Optic figures out what changed, what kind of changes were made and reports that back to your team.

What kind of analysis does Optic do?

  • What Changed. Optic notes what endpoints changed and how they changed.

  • Breaking Changes. We help pinpoint and highlight changes that will require API consumers to update their code.

  • Standards. Optic includes built-in support for naming standards and supports running Spectral rules to help your team define standards for how APIs should be defined.

  • Custom Rules. We get it - your team has custom requirements. We can help you define custom rules against your API specs that meet whatever needs your team has. Enterprise plans only.

Once analysis has completed, Optic records all of this data so that you have a full history of your API and its changes.

3. Review

Once analysis is done, your team has a great source of data about your APIs history. Optic provides numerous outputs from analysis that help your team work more efficiently and share your APIs with whoever consumes them:

  • Changelog. Optic generates a changelog for your API to help developers and consumers keep up to date.

  • Diffs. We display specific diffs for changes so you can see exactly what changed.

  • Metrics and Graphs. Optic helps your team track and visualize how often APIs change and what endpoints change most.

  • Pull Request Feedback. If you run Optic in CI, we share information back to your Pull Requests (GitHub) or Merge Requests (GitLab) to help your team keep up to date and avoid breaking changes or standard non-compliance where they work.

  • Docs and Catalog. We track all APIs your team has and generate documentation for each version of each API, so that your team can alway discover APIs and their latest documentation.

Don’t worry - review isn’t an all at once process. Optic helps your team answers the questions you have, when you have them.

Ready to improve your APIs?

Start using Optic today. No credit card required.