Skip to main content

IPA-102: Resource Identifiers

Most APIs expose resources (their primary nouns) that users can create, retrieve, and manipulate. Additionally, resources are named meaning each resource has a unique identifier that API consumers use to reference that resource.

State

Adopt

Guidance​

  • The full resource identifier is a URI without transport protocols (schemeless)
    • Fully qualified paths
  • All resource identifiers defined by an API must be unique
  • Resource identifiers must use the slash (/) character to separate individual segments of the resource identifier
    • Double slashes (//) must not be used
  • Resource identifier components should alternate between:
    • Collection identifiers (example: groups, clusters, orgs, users)
      • Collection identifiers must be in camelCase
      • Collection identifiers must begin with a lowercase letter and contain only ASCII letters and numbers (/[a-z][a-zA-Z0-9]*/).
      • Collection identifiers must be plural
        • In situations where there is no plural word ("info"), or where the singular and plural terms are the same ("moose"), the non-pluralized (singular) form is correct.
    • Resource IDs (example: groupId, clusterName, orgId)
      • Resource IDs should be server-generated unique identifiers rather than human-readable, client-provided identifiers
        • Server-generated unique identifiers (e.g., UUIDs, auto-generated IDs) are immutable and globally unique
        • Human-readable identifiers (e.g., names, types) may change over time or have uniqueness constraints that are difficult to maintain
        • In some cases, API producers might decide to use a human-readable identifier (e.g., clusterName), however using a system-generated unique identifier is recommended for long-term stability and flexibility
      • Resource IDs should follow the format <resourceName>Id
        • Where <resourceName> is the singular form of the collection identifier
        • Example: for collection groups, the resource ID should be groupId
      • Resource IDs must be in camelCase
      • The resource ID used in the resource identifier (as the URI path parameter) must match the field name used in the resource representation
        • This ensures consistency between the resource identifier and the resource representation
        • Example: if the resource identifier uses groupId, the resource itself must have a field named groupId
  • Resource identifiers should not use abbreviations
    • Unless the abbreviation is well understood, for example, IP, AWS, TCP
  • Resource identifier must not include file extensions such as .gz,.csv, .json
    • The file extension must be only included as media type in the Accept Header.
    • Examples:
      • Accept: application/zip
      • Accept: application/json
      • Accept: application/xml
      • Accept: application/gzip

Example

  • Group identifier /groups/{groupId}
  • Cluster identifier /groups/{groupId}/clusters/{clusterName}
  • User collection identifier /orgs/{orgId}/users

Nested Collections​

If a resource identifier contains multiple levels of a hierarchy and a parent collection's name is used as a prefix for the child resource's name, the child collection's name may omit the prefix.

note

Relationships between resources expressed as nested collections or hierarchical relationships have certain implications that API producers need to consider

  • Nested collections imply a cascade effect
  • Deleting a parent must delete associated children
  • Access to the parent may imply access to children
  • Children must not belong to multiple parents