Make your APIs a little better every day

Nicholas Lim 2023-11-15

Software development is messy, especially in a fast growing company. When companies double their headcount in 6 months and growth is everything, things like consistency and standards are the first thing to go. A lot of companies work in feature teams that build their own services that eventually need to tied together.

Everything moves fast until the moment you need to put all of it together. Then the diverging API patterns and inconsistencies really bog teams down.

How can teams work autonomously and still ensure the pieces they build fit together nicely and are easy to use? One way to standardize your company’s APIs is to use an API linter, but traditional linters are all-or-nothing. You can’t turn them them on without emitting tons of errors from all the APIs you have already built.

Optic tests that each API change your team makes will not break other services (backwards compatible) and brings the services closer to your shared design standards. You don’t have to rework everything, you just have to start getting a little better each day.

There are a few reasons we think that supporting incremental changes to APIs is better:

• Standardizing your API no longer requires a rewrite of your entire API surface area. ****
  • Adding standardization to your API now has a much lower cost and changes can be made incrementally, rather than trying to schedule in a large project.
• Only relevant errors are shown to a developer making those changes
  • Other errors that aren’t related to a developer’s code changes are usually ignored, which makes it easy to start tuning out linting suggestions.
• You don’t need to pick a perfect API style guide
  • Introducing new API rules no longer means a brand new version which makes it easier to add new rules to your API and promote iterative improvement.

Optic comes bundled with rulesets you can start using to standardize your APIs. These include:

• Consistent naming rules [https://www.useoptic.com/docs/style-guides/naming (opens in a new tab)]
• Requiring documentation [https://www.useoptic.com/docs/style-guides/documentation (opens in a new tab)]
• Requiring examples in API documentation [https://www.useoptic.com/docs/style-guides/examples (opens in a new tab)]

These rules can be configured to rule on your entire OpenAPI spec or only when something new is added.

To get started, start by downloading Optic

npm i -g @useoptic/optic

Next, create an optic.yml in the root of your repository with the following ruleset configuration (see [https://www.useoptic.com/docs/style-guides (opens in a new tab)] for other rulesets you can configure).

ruleset:
	# Enforce naming conventions in your API
  - naming:
      required_on: always
      requestHeaders: Capital-Param-Case
      responseHeaders: Capital-Param-Case
      properties: snake_case
      pathComponents:  param-case
      queryParameters: snake_case
 
  - examples:
      # 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
      required_on: added
      # 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
 
  # Require documentation in your OpenAPI spec
  - documentation:
      # 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
      required_on: added
      require_property_descriptions: true
      require_operation_summary: true
      require_operation_description: true
      require_operation_id: true
      # (optional) allow certain operations do not need examples
      exclude_operations_with_extension: x-legacy-api

Next, you can run these checks against an OpenAPI spec. Since we are only requiring documentation and example on new endpoints, we need to provide a before and after spec. In Optic, we use optic diff --check to compare and run change based rules.

optic diff openapi.yml --check --web --base HEAD~1

You can change --base to any git reference (like main or a specific commit hash).

Using Optic’s built in rulesets are a great way to start standardizing your API incrementally without needing to do a big rewrite of your entire API.

Set up in CI

By setting up Optic in CI, you can make sure these checks run every time that your API changes. Setting up Optic in CI will also add an OpenAPI preview, a detailed diff view of your changes and any issues it found using the ruleset you configured. Follow our guide to set up Optic in CI (opens in a new tab)