Forwards Only Checks

Forwards only checks

Linters are a great way to standardize your endpoints, but most of the time you already have existing endpoints that don't match your lint rules. Optic's rule runner is built to support only running rules on newly added endpoints, requests and responses.

Optic can run checks on both json and yaml OpenAPI files and is compatible with your existing spectral rules.

Configuring your rules

Get started by creating an optic.yml file at the root of your repository, and copying in the following rulesets:

  # Enforce naming conventions in your API
  - naming:
      required_on: added
      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: added
      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

Notice that we've set required_on to added - this means that these rules will only run on newly added endpoints or fields!

Using Spectral

Optic also supports interopability with your existing Spectral rules, where you can configure your Spectral rules to only run on newly added endpoints, requests and responses! 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.

  - spectral:
      # You can also point this at your own `spectral.yaml` file!

This will run your existing spectral rules, but only trigger when a new endpoint or field is added!

Diffing your files


Since we're only running rules against newly added endpoints, we need to have two versions of a spec to compare

Once you've set up your rules, it's as simple as running

optic diff my-spec.yml --base HEAD~1 --check
# Or alternatively, if you are on a different git branch
optic diff my-spec.yml --base main --check
# Or even diff two different files!
optic diff my-spec-v1.yml my-spec-v2.yml --check

Add --web to the end of this command to open up a detailed web view of the diff and changes!

What's next?

Forwards only governance isn't the only thing Optic can do! Take a look at some of our other guides: