Skip to main content

API Standards

The Optic community has built several API Standards that your team can adopt today. These open standards are a great place to start because they can be set up in minutes and are high-impact. We suggest adopt some of these first, and incrementally add your own automated standards.

Prevent Breaking Changes

Breaking your API consumers is one of the worst things an API team can do. It is also completely preventable. Defining a breaking change is difficult for many engineers -- it is not always obvious that changing the data model in a subtle way will break consumers. This is a great place to add automation, and help developers understand the impact of their changes.

optic.dev.yml
rulesets:
- breaking-changes:
exclude_operations_with_extension: "x-draft" # skips operations with x-draft:true
Add Breaking Change Standard

Consistent Casing and Naming

When the names in your API have inconsistent casing (ie some properties are camelCase and some are PascalCase) it makes it much harder for developers to read the API documentation and responses. Constantly having to switch the mental parsers they use when reading the names is your APIs brings a lot of cognitive load. Even if your API is great in every other regard, inconsistent naming will leave developers thinking your API is hard to use. Adding a naming standard is a very high-impact standard that is easy to adopt.

optic.dev.yml
rulesets:
- naming:
requestHeaders: Capital-Param-Case
queryParameters: param-case
responseHeaders: Capital-Param-Case
cookieParameters: param-case
pathComponents: snake_case
properties: snake_case
Add Consistent Naming Standard

Documentation includes valid examples

The best API documentation is full of examples. Schemas are important, but when it comes to actually making requests and understanding how your API will response, nothing beats examples. Over time your APIs will change and it is often difficult to keep the examples in your OpenAPI file in sync with the schemas. The only thing worse for your documentation than having no examples, is having examples that are wrong. Requiring up-to-date examples is one of the highest-impact standards you can adopt, especially if your OpenAPI document powers public documentation.

optic.dev.yml
rulesets:
- examples:
require_request_examples: true
require_response_examples: true
require_parameter_examples: true
Add Valid Examples Standard

More resources