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.
Optic visualizes API changes in Pull Requests, and flags design choices which go against your standards.
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)
Want to ship a better API?
Optic makes it easy to publish accurate API docs, avoid breaking changes, and improve the design of your APIs.
Try it for free