Skip to main content
  1. Consistent Casing Naming

Consistent naming in API designs

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.

Usage

Add the naming standard to your optic.dev.yml file. You can learn more about configuring your API standards here:

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

You can set a different case rule for all the named entities in your API (ie headers, cookies, schema properties, etc.).

Supported cases

  • snake_case
  • camelCase
  • Capital-Param-Case
  • param-case
  • PascalCase

Applying naming rules

requestHeaders (optional): the case you want to enforce for request headers queryParameters (optional): the case you want to enforce for query parameters responseHeaders (optional): the case you want to enforce for response headers cookieParameters (optional): the case you want to enforce for cookies pathComponents (optional): the case you want to enforce for the components in your paths (ie /resource/{id}/shipping_address) properties (optional): the case you want to enforce for schema properties

Don't get in the way

If you already have an API, it is likely that there are a few instances where the casing rules have not been followed. Maybe today you use snake_case but one team used camelCase for schema properties. Changing all those schema properties to snake_case would introduce breaking changes? The issues Optic would find are unfixable. So what do you do? We don't want to get in the way of developers.

Enter the applies option: applies (optional): when the naming rules should be enforced

  • always - any invalid naming will be an issue
  • added - naming is only enforced on entities added to the OpenAPI, existing names that were already in the spec are skipped. These means everything you add going forward will follow the naming rules, but legacy operations are exempted form the requirement.

We want our automated API tools to have a high signal / noise ratio so developers pay attention. Many teams find that enforcing their naming rules on added strikes the right balance and never asks developers to follow one standard (a name) by breaking another standard (no breaking changed allowed).

Issues and contributing

Help your developers ship better APIs

Optic makes it easy to track, review, and test every API change so your can build the right API, the first time.