Skip to content

Resource Scope and Hierarchy

What is a resource layout?

The arrangement of resources in our API, the fields that define those resources, and how those resources relate to one another through those fields.

In other words, resource layout is the entity (resource) relationship model for a particular design of an API.

Types of Relationships

Reference Relationships

The simplest way or two resources to relate to one another is by a simple reference.

A message resource contains a reference to a specific user who authored the message.
  • This reference relationship is sometimes referred to as a foreign key relationship.
  • As a result, this can also be considered a many-to-one relationship.
    • A user might write many messages, but a message always has one user as the author.

Self-Reference Relationships

An employee resource points at other employee resources as managers and assistants.

Hierarchical Relationships

  • Hierarchical relationships are sort of like one resource having a pointer to another
    • But that pointer aims upward and implies more than just one resource pointing at another.
  • Hierarchies also tend to reflect containment or ownership between resources.
ChatRoom resources act as the owner of Message resources through a hierarchical relationship.

In this case, there is an implied hierarchy of ChatRooms containing or owning Messages.

Choosing the Right Relationship

Do you need a relationship at all?

When building an API, after we've chosen the list of things or resources that matter to us, the next step is to decide how these resources relate to one another.

  • Consider a self-reference relationship between Users. A single change to one resource can affect millions of other related resources.
  • e.g. if someone famous deletes their Instagram account, millions of records might be to be removed/updated.

Reference relationships should be purposeful and fundamental to the desired behaviour. Any reference relationship should be something important for the API to accomplish its primary goal.

References or in-line data

  • Where data is in-lined, we only need a single API call to retrieve all the relevant information.
  • But what if we aren't interested in that information very often?
    • Then our response is bloated.

Optimise for the common case - without compromising the feasibility of the advanced case.

Hierarchy

The biggest differences with this type of relationship are the cascading effect of actions and the inheritance of behaviours and properties from parent to child.

  • Deleting a parent resource typically implies deleting a child resource.
  • Access to a parent generically implies the same level of access to the children resources.

Anti-patterns

Resources for Everything

It can often be tempting to create resources for even the tiniest concept you might want to model.

Rule of thumb: If you don't need to interact with one of your resources independent of a resource it's associated with, then it can probably be a data type.

Deep Hierarchies

Overly deep hierarchies can be confusing and difficult to manage.

Page 63 4.3.3 in-line everything