Skip to main content

IPA-112: Field Names

Naming fields in a way that is intuitive to users can often be one of the most challenging aspects of designing an API. This is true for many reasons; often a field name that seems entirely intuitive to the author can baffle a reader.

Users rarely use only one API; they use many APIs together. As a result, a single company using the same name to mean different things (or different names to mean the same thing) can often cause unnecessary confusion.

It's important to keep consistency to allow users take what they've already learned from one API and apply that to another.

In short, APIs are easiest to understand when field names are simple, intuitive, and consistent with one another.

State

Adopt

Guidance​

  • Field names should communicate the concept being presented and avoid ambiguous names
    • Field names should avoid including unnecessary words
  • Field names must use camelCase
  • Fields must not contain leading, trailing, or adjacent underscores(_)
    • id not _id
  • Field names should not use abbreviations
    • Unless the abbreviation is well understood, for example, IP, AWS, TCP
  • APIs should aim to use the same name for the same concept and different names for different concepts wherever possible
    • Including across APIs and resources
    • Names should follow/be unified between GUI and API
  • Repeated fields must use the proper plural form
  • Field names must not be named to reflect an intent or action
    • Fields must not be verbs
    • disabled not disable
  • Boolean fields should omit the prefix "is"
    • disabled not isDisabled
  • Field names of common conventions must use the same field name and description as existing fields
  • Field names must refer to a singular concept when used across APIs
  • Existing concepts must map to a singular field name
  • For enum fields the allowable values may differ from values allowed in other instances of the field
  • Field names must be consistent in between the request, response body and path parameters

Group vs. Project​

  • For consistency APIs must use "group," "groups," "groupId" over "project," "projects" or "projectId"