Core Concepts
Under the hood Optic is a version control tool (think git) for OpenAPI. In Optic there are two kinds of diffs: traffic to spec, and spec to spec. Optic's core use cases are just built on top of these diffs. Preventing breaking changes is just subscribing to spec Δ spec diff results for events like property.removed
. Documenting your API from traffic is just transforming traffic Δ spec diffs into patches to your OpenAPI.
Diff functions
Traffic to spec
Optic can diff HTTP logs (in the HAR format) against the behavior of the API in the specification. Undocumented paths/methods will show up as "undocumented operations" that you can add to the specification, and changes to an existing response/request/parameter will show up as "diffs".
The optic verify
and optic update
commands are all built on traffic Δ spec diffs.
Spec to spec
Optic can diff any two versions of an OpenAPI specification. The result of a spec Δ spec diff is an API changelog. Unlike a simple json diff, Optic's semantic changelog understands the OpenAPI domain and will only show you actual changes in the API. You could add $refs, refactors your schemas, etc and if the behavior is the same Optic won't show a diff.
You can render these changelogs in CI to help everyone on the team do effective API Change Reviews, and you can use these changelogs to test for breaking changes and enforce your API style guide. Think of this as testing the API changes -- that's essentially how it works. Optic lets you listen for certain kinds of changes between versions ie parameter.added
and write assertions.
OpenAPI patching (not generating)
Many tools will generate an OpenAPI specification from traffic, but you are not able to run those generators over and over again. If you do, they will delete your manual contributions like descriptions or more specific schemas. What makes Optic unique is that it never "generates" a specification, it patches the existing one you give it. That is why you have to pass Optic an OpenAPI in every optic update
command.
Optic will transform the traffic Δ spec diffs it detects into small json patches to your OpenAPI specification, which it will then apply. It makes surgical patches to your spec, just like a developer would -- they don't rewrite the whole spec when one type changes. Because Optic works this way, you could continue using it to document and update your spec for years instead of just once.
The optic diff
command is built on spec Δ spec diffs.
API Coverage and OpenAPI Accuracy
Whether you work design-first or code-fist, it's hard to know whether your OpenAPI spec accurately describes your real API. optic verify ...
solves this problem. All this command does is take traffic from your tests, manual QA, or from a real environment exits 1
when any traffic Δ diffs are detected. That's not very useful unless you know how much of your API is being tested. This is where coverage comes in. Optic will compute the % of your OpenAPI specification that has been verified. No diffs and high coverage is a strong signal that your API works as-designed:
» Verifying API behavior...
API Behavior Report
Total Requests : 128
Diffs : 0
Undocumented operations : 0
Undocumented bodies : 0
Coverage Report 75.0%
●●●● get /users/{user}/followers
60 200
●●◌◌ get /users/{user}/starred
25 200
●●◌◌ get /gists/{gistId}
17 200
●●◌◌ get /users/{user}/gists
16 200
●◌◌◌ get /users
10 200
◌◌◌◌ get /users/{user}/subscriptions
0 200
No diffs detected. OpenAPI and implementation appear to be in sync.
Forwards-only governance
Many teams who use API-specific linters like Spectral have found that static linting does not work well for API specifications. If you write a lot of API standards for an existing API, you create a Catch-22 -- the only way to get the lint rules to pass is to make breaking changes, which everyone is trying to avoid. Developers turn off the rules OR stop paying attention.
When Optic runs your Spectral, ReDoc or Optic rules, it can apply different rules to your additions
than your existing operations. This is really valuable because it lets teams enforce their latest standards for new APIs, while also allows existing APIs to continue working as they were initially designed to. The signal noise ratio is really strong and developers always know what is important to fix, and what is not. Teams like Snyk who value API consistency across their entire company have migrated their API governance tooling (opens in a new tab) from Spectral to Optic because it is their developers actionable feedback on all the API changes they make.