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.
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)