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