🎉 Optic is joining Atlassian Read more →
Docs
API Style Guides
Naming

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

Supported Cases

  • param-case
  • Capital-Param-Case
  • camelCase
  • snake_case
  • PascalCase
  • case-insensitive-param-case (first letter can be case insensitive - e.g. X-header will pass but X-heaDer will not)
ruleset:
  - naming:
      required_on: always
      requestHeaders: case-insensitive-param-case
      responseHeaders: param-case
      properties: Capital-Param-Case
      pathComponents:  param-case
      cookieParameters:  param-case
      queryParameters: param-case
      operationId:  camelCase

Options

required_on always | added:

Do naming rules apply to all entities in your API always (legacy + new endpoints), or just new endpoints and their parameters + properties added.

We suggest using added so your legacy endpoints won't fail the lint rule.

requestHeaders(optional): Most APIs use Capital-Param-Case or case-insensitive-param-case headers, but Optic will let you check for any case.

responseHeaders(optional): Most APIs use Capital-Param-Case or case-insensitive-param-case headers, but Optic will let you check for any case.

properties(optional): Most API bodies use snake_case, camelCase or PascalCase for their body properties.

pathComponents(optional): Most API URL paths use snake_case or param-case.

queryParameters(optional): Most query parameters use Capital-Param-Case or param-case.

cookieParameters(optional): Most query parameters use Capital-Param-Case or param-case.

operationId(optional): Enforce naming conventions for operationIds in OpenAPI operations. You probably want to use camelCase or snake_case

Breaking ChangesLintGPT