A reference is a pointer stored in one resource that identifies official data held elsewhere. In an API, a Message can store an author reference to a User, creating a many-to-one relationship. References are useful when the relationship is fundamental, but every relationship carries long-term design and performance costs. section 4.1.1 section 4.2.1
Use references deliberately and define their behavior explicitly:
- Name a static reference field for both its target type and purpose, such as authorId on Book; use an additional targetType field when the target type varies. section 13.3.1
- Represent references with string identifiers, allowing targets in the same API, another provider API, or elsewhere on the internet through a URI. section 13.2
- Expect references to become stale or invalid when their targets move or are deleted; consumers should check them rather than assume they remain valid. section 13.2 section 13.3.2
- Choose a reference instead of in-line data when freshness and a single official value matter more than avoiding an additional request. section 4.2.2 section 13.3.3
- Avoid relationships that are merely accidental or convenient; retain them when they are fundamental to the API’s behavior. section 4.2.1
Book and author
A reference-based design stores authorId rather than duplicating the Author resource: Book { id, authorId, title } and Author { id, name }. Reading an author’s name requires retrieving the book and then retrieving the author. An in-line design provides the name in one response but must address stale copied data. section 13.3.3 section 13.3.4
Deletion and integrity
Create an Author, create a Book with authorId set to the author’s identifier, and then delete the Author. The Book may retain an invalid reference. Resetting every affected Book could require many updates and may not be atomic, so consumers should be prepared to detect invalid references. section 13.3.2
Listing 13.1 Definition of Author and Book resources
interface Book {
id: string;
authorId: string; #1
title: string;
// ... #2
}
interface Author {
id: string; #3
name: string;
}
The resource definition makes the authorId naming convention and the separation between Book and Author concrete. section 13.3.1
