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.

optic diff openapi.yml --check

Configuring your lint rules

Get started by creating an optic.yml file at the root of your repository, and copying 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

Forwards-only governance

Governing APIs that have already shipped to consumers is really difficult. If you turn on an API linter like Spectral to enforce an style guide it will ask developers to make breaking changes to meet the style guide. Optic has a unique approach to this problem -- lifecycle rules.

Every Optic lint rule can be set to run on certain kinds of changes. For example, if you set your naming rules to be required_on: added only new endpoints will have to follow them. Legacy endpoints that may not will not warn/error because changing them would be breaking changes.

required_on: always | added | addedOrChanged | removed

To use forwards-only governance and breaking change rules you will need to switch over to using the diff command:

optic diff openapi.yml --base main --check

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 diff openapi.yml --base main --check

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")
})