Skip to main content

IPA-126: Top-Level API Names

Top-level API names direct customers to the core services or functional areas that service their needs. These names need to be intuitive, clear, and easily recognizable to facilitate seamless navigation of API documentation.

State

Adopt

Guidance​

  • API names must use ‘Title Case’
  • API names must be written as nouns
    • For example: 'Alert Configurations' not 'Configure Alerts'
  • API names should be precise and self-explanatory to convey the function of the APIs
  • API names should not include platform-specific branding or terms
  • APIs for platform services should not include the platform name
    • For example, 'Atlas Search' should be displayed as 'Search'
  • Discoverability through search should be considered to facilitate fast identification
  • API names should avoid using acronyms unless widely recognized

OpenAPI Consideration​

  • When defining tags in OpenAPI Specification, these naming principles should be applied
  • Each tag should represent a logical grouping of APIs, aligning with top-level service areas to enhance discoverability and navigation