Developer-friendly API Governance
Optic has an API linter built for the messy real-world. You can use it to govern APIs that have already shipped, without getting in the way of developers. Optic makes sure the additions to your API follow the latest standards and understands that existing API endpoints cannot be updated without introducing breaking changes. Get the benefits of Spectral, Redocly and other API Linting tools without all the noise.
Get started by creating an optic.yml file at the root of your repository, and copying in the following:
- ✅ Run any of your existing Spectral (opens in a new tab) Rules
- ✅ Catch Breaking Changes
- ✅ Support Advanced style guides for things like pagination
- ✅ Enforce a versioning policy (ie require semantic versioning)
Optic Cloud Subscriptions include several free API Governance consults. If you want help choosing API standards Book a session here (opens in a new tab)
The community maintains many useful off-the-shelf standards. Here's an example
optic.yml file you can copy to your repo to get started:
ruleset: # Prevent breaking changes - breaking-changes: # Pick an extension for your work-in-progress operations. # Breaking changes will be allowed here exclude_operations_with_extension: x-draft # Run any spectral ruleset - spectral: # These rules will ony run on things you add to your API # Ie new properties, operations, responses, etc. added: # URLs are supported - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a # Local files work too. # - ./local-file.js # These rules will ony run on everything in the spec (normal spectral) always: - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a # Enforce consistent cases in your API - naming: # This will apply the rule to only new names (existing ones will be exempted) # Change to always if you want to fail on legacy names # Change to addedOrChanged if you want it to run on added or changed parts of the spec required_on: added # Different names for different parts of the spec # options = "snake_case" "camelCase" "Capital-Param-Case" "param-case" "PascalCase" 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: # Turn on/off the parts of the spec that need examples 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
Because Optic tests your API changes, you run standards with the
optic diff openapi.yaml --base main --check --ruleset ./optic.dev.yml
This tests the changes between the working copy of
openapi.yaml and the version on the
main branch. It runs the rulesets as configured in
optic.dev.yml and prints the results to the console. If you would like to see the errors formatted in the browser, pass in the
Optic Cloud allows API Programs to set their team's standards in Optic Cloud, and apply them to multiple API specs. This way when the standards are changed, everyone gets the update quickly. Go to your team's organization
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).
Need more than the community standards? Want to do something too advanced for Spectral? Optic has a framework for testing API Changes that all the community standards are built upon.
- Snyk's V3 API Standards (opens in a new tab)
- Breaking change standards (opens in a new tab)
- Casing and Naming standards (opens in a new tab)
- Examples must match schema standard (opens in a new tab)
If you are interested in writing custom rules for your team you can also book a session here (opens in a new tab).