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)

Setting API Standards

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
 

Running the Standards

Because Optic tests your API changes, you run standards with the diff command

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 --web flag:

Sharing API Standards

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 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).

Advanced Standards and Style Guides

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.

Notable examples:

• 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).