Core Concepts

Optic keeps track of an API's endpoints, behavior and changes over time. From a high level an API is a collection of specs (which is a point in time snapshot of the OpenAPI spec), containing the history and changes between specs.

Whenever an API changes, Optic uploads the new spec and tags the spec with contextual data (like the git branch and commit sha). If the spec includes branch information Optic runs a diff against the previous version of the spec.

APIs

An API is a collection of specs (point in time snapshots of OpenAPI specs). APIs are tracked with how they change over time, contain statistics and trends, and can be used to compare between different versions of the API at different points in time.

Specs

In Optic, a spec is the point in time representation of an API's behavior (i.e. a snapshot of the OpenAPI spec at a certain git commit). When you run the optic diff command, it runs against two different spec versions.

Diffing between specs

When Optic diffs two specs, it runs a behavior diff rather than a single object diff. Unlike a simple object diff, Optic's behavior diff 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.

Tags

A spec also contains tags which ties it back to where it originated from (e.g. a git commit and a git branch). Tags can either be used as unique identifiers (e.g. the version of the API at a certain date) or as moving pointers (e.g. the current version in production). Some of the ways you can use tags are:

• Every time you make a production release, you can tag the latest spec as env:production
  • This will overwrite the previous env:production tag and set it as a previous version
• If you have a more controlled release process, you could also tag your API with semantic versioning - e.g. 1.7.2

Tags can be used to easily refer back to specific versions of your API, or to compare against previous versions with the same tag. In Optic Cloud, you can diff between different tags, or against a previous tag.

Default tag

The default tag in Optic Cloud is used to determine the default tag to use when displaying documentation. Certain statistics only run on the default tag like changes over time.

Usually this just maps to the gitbranch:main tag or whatever your default branch is in your git repository, but you could also change your default tag to point to env:production if you set up a script to update the tag whenever you deploy your API. This is particularly useful if your git default branch isn't in sync with what's running in production.

Standards

Standards are ways to enforce standardization and prevent unwanted API changes, such as breaking changes. Optic comes included with standard rulesets such as naming and breaking-changes and interop with spectral using our spectral standard ruleset. A standard is a collection of rules which are used to help standardize your API.

Lifecycle

Traditional OpenAPI linters such as spectral only run static linting, which make it impossible to introduce new standards as adding a new standard creates a Catch-22: the only way to fix linting errors is to create a breaking change. Take naming rules for an example, if you add in a rule that requires all camelCase response properties on an API that already has snake_case response properties, you cannot add these rules. Developers turn off the rules or stop paying attention.

Optic solves this by allowing you to specify different lifecycles where rules can run. You can configure rules to run when something is added, changed, removed or always, which lets you incrementally introduce new standards without disrupting developers.

Capture

Optic can capture traffic from an API. Since captured traffic comes from the actual behavior of the API, we can do two things with it:

• Verify the spec against the implementation
• Update the spec to match what traffic was seen

A lot of teams struggle with documentation drift (OpenAPI spec does not match the behavior). Optic can help solve these problems, some of the ways that Optic can be configured include:

• Connecting optic capture to CI tests and verifying the behavior
• Generate OpenAPI specs from captured traffic