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