Resource layout

As explained in API Design Patterns

A resource hierarchy is the organization of API resources into nested parent-child paths and collections.

Resource layout organizes an API’s resources, fields, and relationships. It determines which concepts become resources, how they associate, and whether clients interact with them through separate collections or nested hierarchies. section 4.1

Figure 4.1 A chat room contains lots of user members.

Use the chat-room relationship diagram to see how one ChatRoom resource can relate to many User resources. section 4.1

Choose relationships deliberately:

• Create a relationship only when it provides important, fundamental API behavior; large fan-out relationships can make one change affect millions of records. section 4.2.1
• Make a concept a separate resource when it needs independent, atomic interaction; otherwise, inline it as a data type. section 4.5
• Avoid overly deep hierarchies because they become difficult to understand and manage. section 4.5
• Treat frequent custom methods as a warning that resources or relationships may be poorly chosen rather than using methods as design duct tape. section 9.4

Centralized operations

For long-running operations, place Operation resources in a top-level collection such as /operations/1 rather than scattering them beneath individual resources. A centralized collection supports discovery across the system and handles operations that are not centered on one resource. section 10.3.2

Reconsider a parent-child relationship when copying, moving, or renaming resources becomes difficult. Such problems may indicate poorly chosen identifiers or a relationship that should have been referential instead. section 17.4

How API Design Patterns covers it

How deep it goes

Explains resource selection, relationship costs, hierarchy depth, and anti-patterns, but stops short of implementation details.

Examples

Uses chat rooms with users, shopping users with addresses and payment methods, follower self-references, and centralized Operation resources.

What it assumes

Assumes familiarity with API resources and standard methods while teaching relationship selection through concrete API scenarios.

What you can do after

Evaluate resource boundaries and relationships before committing to hierarchies, references, or custom methods.

How it connects

Connects REST, API resources, entity relationship models, custom methods, long-running operations, and copy and move operations.

liveBookmanning.com

Read API Design Patterns on liveBook Get the book at manning.com

Related concepts

• resourceuses · An API resource is a conceptual entity or target exposed through an interface and addressable for access or manipulation.
• entity-relationship modelkind of · An entity-relationship model is a data model representing entities, their attributes, and the relationships among them.
• singleton sub-resourcecontrasts with · A singleton sub-resource is an API sub-resource representing one distinct related entity rather than a collection of entities.
• move methodcontrasts with · A move method is an operation that relocates an existing resource or item to a different location or parent while preserving its identity.
• entity-relationship diagramused by · An entity-relationship diagram is a visual model representing data entities, their attributes, relationships, and applicable constraints.
• antipatterncontrasts with · An antipattern is a recurring approach that appears reasonable but tends to produce undesirable or counterproductive results in a given context.

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.