13 Cross references

 

This chapter covers

  • What names fields should use when referencing other resources
  • How reference fields should handle issues with referential integrity
  • When and why fields should store a copy of the resource data

In any API with multiple resource types, it’s likely that there will be a need for resources to point at one another. Though this manner of referencing resources may appear trivial, many of the behavioral details are left open for interpretation, which means there is the opportunity for inconsistency. This pattern aims to clarify how these references should be defined and, more importantly, how they should behave.

13.1 Motivation

Resources rarely live in a vacuum. As a result, there must be a way for resources to reference one another. These references range from the local (e.g., other resources in the same API) to the global (e.g., resources that live elsewhere on the wider internet) and may fall in between as well (e.g., resources in a different API offered by the same provider) (figure 13.1).

Figure 13.1 Resources can point at others in the same API or in external APIs.

13.2 Overview

13.3 Implementation

13.3.1 Reference field name

13.3.2 Data integrity

13.3.3 Value vs. reference

13.3.4 Final API definition

13.4 Trade-offs

11.5 Exercises

Summary