14 Association resources

 

This chapter covers

  • How to handle many-to-many relationships with association resources
  • What name to choose for association resources
  • How to support standard methods for association resources
  • Strategies for handling referential integrity

In this chapter, we’ll explore a pattern for modeling many-to-many relationships between two resources using a separate association resource to represent the connection between the two. This pattern allows consumers to explicitly address an individual relationship between two resources as well as storing and managing extra metadata about that relationship.

14.1 Motivation

Most of the time, the relationships we’ll define between resources in an API will be simple and obvious because they tend to be unidirectional in nature, acting as pointers or references going from one resource to another (e.g., database 1 belongs to project 1), as shown in figure 14.1. When one resource type refers to another in this way, we say they have a one-to-many relationship. While these types of relationships are typically easy to manage when designing an API (often just a property referencing the other resource), there are other times the relationships needed are more complicated and, as a result, are more difficult to express in an easy-to-use API.

Figure 14.1 Unidirectional, or hierarchical, relationships between resources

14.2 Overview

14.2.1 Association alias methods

14.3 Implementation

14.3.1 Naming the association resource

14.3.2 Standard method behavior

14.3.3 Uniqueness

14.3.4 Read-only fields

14.3.5 Association alias methods

14.3.6 Referential integrity

14.3.7 Final API definition

14.4 Trade-offs

14.4.1 Complexity

14.4.2 Separation of associations