Define your API Standards

Make your team's API Standards and Style Guide easy to learn and easy to follow. Optic guides and supports developers designing APIs.

Teams use Optic's checks to:

• Detect breaking changes between two versions of an OpenAPI file.
• Enforce an API Style Guide.
• Enforce their unique API versioning strategy.
• Require OpenAPI specs use certain x- extensions.

How are Optic Checks different from other API linting tools?

• Our Typescript SDK makes it easy to express a complete API style guide.
• Write Rules about change. Optic Checks can run against two API versions (before and after) to help enforce your versioning strategy, deprecation policy and to detect breaking changes.
• Exclude false positives. Sometimes we can't change the API to pass a rule because doing so would be a breaking change. Optic understands this and makes it possible to tune your checks, so they run in the right places and are trusted by developers.

Writing your own checks (in beta)

The Optic Checks SDK is still in Beta and has not reached stability. We're working closely with several teams like Snyk to build the right SDK and release it publicly in coming months. If you would like to join that beta you can by setting up a quick call here.

Using Built-in Checks

First run optic init in your repository:

optic init

This command will find all the OpenAPI specifications in your repo and add them to your optic.yml file:

files:
  - id: todo-api
    path: specs/todo-openapi.yaml
ruleset:
  - "breaking-changes"
  - "naming":
    pathComponents: camelCase

Right now you can configure the naming checks as described here.

More built-ins are coming soon. If you have an idea for a new built-in ruleset, feel free to open an Issue here.

Running API Standards in CI

Optic's changelog view can show the results of all your API standards. Just include the --web flag. This computes the changelog locally and includes it via a URL to Optic's visual changelog view (we do not save the data).

optic diff openapi.yaml --base main --check --web

openapi.yaml

openapi: 3.0.1

paths:
 /todos:
  get:

   parameters:
    - name: limit
      in: query
      schema: 
       type: number
      required: true 

   responses:
    '200':
      content:
       application/json:
        schema:
        type: object
        properties:
         todos:
         type: array
         items:
          $ref: "#/components/schemas/TodoRead"

components:
 schemas:
  TodoRead:
   type: object
   properties:
     name:
       type: string

     status:
       type: string

     status:
       type: number

     tags:
       type: array
       items:
        type: string

     created_at:
       type: string
   required:
     - name
     - status
     - created_at

Enforce your API Standards in CI

You can set up Optic Cloud to test all your team's API changes and apply the API Standards during CI. Learn more about setting up Optic Cloud here.