Skip to main content
Adopt

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.

Guidance​

  1. Lint rule ↗

    API names must use 'Title Case'.

    tags:
      - name: Alert Configurations
      - name: Billing and Invoices
    Why:

    Each significant word is capitalized, and the grammatical word "and" stays lowercase, which is the conventional Title Case form.

    tags:
      - name: alert configurations
      - name: Billing And Invoices
    Why:

    The first tag is all lowercase, and the second capitalizes the grammatical word "And", so neither follows Title Case.

  2. API names must be written as nouns. For example, 'Alert Configurations' not 'Configure Alerts'.

    tags:
      - name: User Invitations
      - name: Project Members
    Why:

    Each name labels the thing the API manages rather than an action taken on it, so the name reads as a service area.

    tags:
      - name: Invite Users
      - name: Manage Project Members
    Why:

    Each name leads with a verb, describing an action instead of naming the functional area, which reads as an operation rather than a top-level service.

    1. Collect every entry under tags and read each name.

    2. For each name, identify the leading word and decide whether it is a verb or an action phrase ("Configure", "Manage", "Create", "Invite").

    3. Confirm the name reads as a noun phrase naming a functional area rather than an action.

    4. Report any tag name that is phrased as a verb or action.

  3. API names should be precise and self-explanatory to convey the function of the APIs.

    tags:
      - name: Payment Methods
      - name: Scheduled Reports
    Why:

    Each name states the functional area plainly, so a reader knows what the API covers without consulting other documentation.

    tags:
      - name: Misc
      - name: Core Service
    Why:

    "Misc" and "Core Service" are vague and convey nothing about the function the API serves, leaving a reader to guess what the group contains.

    1. Collect every entry under tags and read each name.

    2. For each name, decide whether it names a specific function or is generic filler ("Misc", "Other", "General", "Core").

    3. Cross-check the operations grouped under the tag and confirm the name accurately and specifically describes them.

    4. Report any tag name that is vague or does not describe the operations it groups.

  4. API names should not include platform-specific branding or terms.

    tags:
      - name: Search
      - name: Data Federation
    Why:

    Each name describes the function alone, so it stays meaningful regardless of the product or surface that hosts the API.

    tags:
      - name: Acme Search
      - name: Acme Cloud Data Federation
    Why:

    The branded prefix adds no information about the function and ties the name to a product surface, which clutters the documentation index.

    1. Collect every entry under tags and read each name.

    2. For each name, check whether it contains a product, brand, or trademark term rather than a plain functional descriptor.

    3. Report any tag name carrying branding or platform-specific terminology.

  5. APIs for platform services should not include the platform name. For example, 'Atlas Search' should be displayed as 'Search'.

    tags:
      - name: Search
      - name: Backups
    Why:

    Within a platform's own API, the platform name is implied, so each function is named on its own.

    tags:
      - name: Platform Search
      - name: Platform Backups
    Why:

    Repeating the platform name on every tag is redundant inside that platform's API and pads each name without adding meaning.

    1. Identify the platform or service that owns the specification.

    2. Collect every entry under tags and read each name.

    3. For each name, check whether it begins with or contains the owning platform's name.

    4. Report any tag name that prefixes the function with the platform name.

  6. Discoverability through search should be considered to facilitate fast identification.

  7. API names should avoid using acronyms unless widely recognized.

    tags:
      - name: Access Control
      - name: API Keys
    Why:

    "Access Control" is spelled out, and "API" is a widely recognized acronym, so both names stay clear to a general reader.

    tags:
      - name: RBAC
      - name: SLA Templates
    Why:

    "RBAC" and "SLA" are domain acronyms that a reader unfamiliar with the area cannot decode, which hurts navigation.

    1. Collect every entry under tags and read each name.

    2. For each name, find any token that is an acronym or initialism.

    3. Decide whether the acronym is widely recognized by a general audience or is domain-specific jargon.

    4. Report any tag name relying on an acronym that is not widely recognized.

OpenAPI Consideration​

  1. When defining tags in an OpenAPI specification, these naming principles should be applied.

    tags:
      - name: Payment Methods
      - name: Scheduled Reports
    Why:

    The tag names are nouns in Title Case that name a function plainly, so the same naming principles that govern API names govern the tags.

    tags:
      - name: configure payments
      - name: RBAC
    Why:

    One tag is a lowercase verb phrase and the other an obscure acronym, so the tag names ignore the naming principles applied to API names.

    1. Collect every entry under tags and read each name.

    2. For each name, apply the API-name checks: Title Case, noun phrasing, precise wording, no branding, no platform name, no obscure acronyms.

    3. Report any tag name that violates one of those naming principles.

  2. Each tag should represent a logical grouping of APIs, aligning with top-level service areas to enhance discoverability and navigation.

    tags:
      - name: Billing
    paths:
      /invoices:
        get:
          tags: [Billing]
      /payment-methods:
        get:
          tags: [Billing]
    Why:

    Both operations belong to the same service area and share one tag, so the tag represents a coherent top-level grouping.

    tags:
      - name: Endpoints
    paths:
      /invoices:
        get:
          tags: [Endpoints]
      /users:
        get:
          tags: [Endpoints]
    Why:

    Unrelated operations are lumped under a single catch-all tag, so the grouping reflects no service area and gives a reader no way to navigate.

    1. Collect every entry under tags and the set of operations referencing each tag.

    2. For each tag, inspect the grouped operations and decide whether they form one coherent service area.

    3. Check for catch-all tags that group unrelated operations and for tags that fragment one service area across several names.

    4. Report any tag that does not align with a single top-level service area.