Hierarchical identifier

As explained in The Design of Web APIs, Second Edition

A hierarchical path is a URI path whose segments express parent-child relationships among resources.

A hierarchical path is a URI path whose segments express parent-child relationships among resources. The final segment supplies the fundamental meaning; preceding segments add context. section 4.2.4 section 9.3.2

Catalog products

Use /catalog/123456 or /products/123456 to express that product 123456 belongs to a catalog or product list. Prefer /catalog/123456 over /123456/catalog because the parent precedes the child. section 4.2.4

Design hierarchical paths by applying these checks:

• Give every segment a clear purpose and keep resource naming consistent, such as /accounts/{accountId}/transactions. section 9.3.1 section 9.3.2
• Shorten paths when a globally unique identifier makes parent parameters unnecessary; retain them when identity depends on the parent. section 9.3.3

Figure 9.3 We question user needs and use globally unique IDs to reduce the number of path parameters in the Banking API resources paths and make them easier to use.

Compare banking resource paths and identify where globally unique identifiers can remove unnecessary path parameters. section 9.3.3

How The Design of Web APIs, Second Edition covers it

How deep it goes

Explains hierarchy, naming consistency, path shortening, and identifier scope, but defers detailed path structure to related guidance.

Examples

Uses catalog products, banking accounts, transactions, customers, and addresses to compare hierarchy and path length.

What it assumes

Assumes familiarity with URI paths, resources, identifiers, and standard HTTP methods.

What you can do after

Build API resource paths that communicate relationships, remain predictable, and avoid unnecessary parameters.

How it connects

Connects URI paths with resource identifiers, path parameters, HTTP methods, and globally unique identifiers.

liveBookmanning.com

Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Related concepts

• url pathkind of · A URL path is the hierarchical component of a URL that identifies a resource or route within its host.
• hierarchyuses · A hierarchy is an organization of entities into nested or ordered levels connected by parent-child, containment, or broader-to-narrower relationships.
• parent-child relationshipuses · A parent-child relationship is a hierarchical association in which one entity or component contains, governs, derives, or organizes another.
• ownershipimplements · Ownership is a programming-language model that assigns responsibility for controlling a value or resource, including its lifetime and eventual cleanup.
• unique identifierkind of · A unique identifier is a value or name that distinguishes an entity or record from others within a defined scope or namespace.

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.