Improve your API design
Optic is the first API linter built with the API lifecycle in-mind. Because Optic understands how your API changes over time, it can test for breaking changes and proper use of your API versioning scheme, as well as enforce an API design guide like Spectral.
To get started, create an optic.yml
file at the root of your repository. Then copy in the following rulesets:
ruleset:
# Prevent breaking changes
- "breaking-changes"
# Enforce naming conventions in your API
- naming:
required_on: always
requestHeaders: Capital-Param-Case
responseHeaders: param-case
properties: Capital-Param-Case
pathComponents: param-case
queryParameters: snake_case
# Require your OpenAPI has examples, and that those examples match the schema
- examples:
required_on: always
require_request_examples: true
require_response_examples: true
require_parameter_examples: true
# (optional) allow certain operations do not need examples
exclude_operations_with_extension: x-legacy-api
Now when you update your OpenAPI files, the standards configured in the optic.yml
will be applied:
optic run
| Optic Bookstore Demo Spec (openapi.yml)
| ❌ 1 breaking change ❌ 3 design issues
| View report: https://app.useoptic.com/...report
Using Spectral
Optic can run your existing Spectral rules. To do this, you'll need to ensure you have the spectral-cli
installed:
npm install -g @stoplight/spectral-cli
Once you've installed the spectral-cli
, modify your optic.yml
file with spectral config. You can point at URLs or local spectral YAML files.
Just like the other standards, you can run Spectral rules on added
parts of your API or always
. We suggest putting your latest API design standards in an added
ruleset, and your security and documentation standards in an always
ruleset.
ruleset:
...
- spectral:
# You can also point this at your own `spectral.yaml` file!
always:
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
added:
- ./spectral.yml
optic run
Next steps
Sharing API Standards
Optic Cloud allows API Programs to set their team's standards in a central location and share them across repos and API specs. This way when the standards are changed, everyone gets the update quickly. Go to your team's organization Settings
> Standards
to get started. If you are a Cloud Subscriber we suggest booking a session with us as well to talk about what we have learned helping many teams adopt API Standards: Book a session here (opens in a new tab).

Custom Rules
Optic supports writing custom rules in Spectral's rule format (opens in a new tab) or the Optic API Rule DSL. Optic rules look like this -- you specify a part of the specification you want to check and the kind of change that triggers the rule:
response.property.changed((before, after) => {
if (before.required && !after.required)
throw new Error("Making a response property optional is a breaking change")
})
Run in CI
Calling optic run
in your CI pipeline tests that every API specification is accurate, follows your standards, and contains no breaking changes. Learn more about running in CI here
- OpenAPI is accurate
- ⦿
- No Breaking Changes
- ⦿
- New Endpoints follow v3 API Guidelines
- ⦿