Pattern Sections
Pattern: Linked
Information Holder 
a.k.a. Linked Entity, Data Reference; Compound Document (Sideloading)
Context
An API exposes structured data to meet the information needs of its clients. This data contains elements that relate to each other (for example, product master data may contain other data elements providing detailed information, or a performance report for a period of time may aggregate raw data such as individual measurements). API clients work with several of the related information elements when preparing request messages or processing response messages. Not all of this information is always useful for the clients in its entirety.1
Problem
How can messages be kept small even when an API deals with multiple information elements that reference each other?
Forces
A general rule of thumb in distributed systems is that request and response messages should not be too large so that the network and the endpoint processing resources are not over-utilized. That said, message recipients possibly would like to follow many or all of the relationships to access information elements related to the elements requested. If the related elements are not included, information about their location and their content is required, as well as access information. This information set has to be designed, implemented and evolved; the resulting dependency has to be managed.
When deciding for or against this pattern, you have to consider its impact on:
- Performance and scalability
- Modifiability and Flexibility
- Data quality
- Data privacy
- Data freshness and consistency
Pattern forces are explained in depth in the book.
Solution
Add a Link Element to messages that pertain to multiple related information elements. Let this Link Element reference another API endpoint that represents the linked element.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
A sample application for Customer Management could work
with a Customer Core service API that aggregates several
information elements from the domain model of the application, in the
form of entities and value objects from Domain-Driven Design (DDD). Its
API client could access this data through a
Customer Information Holder, implemented as a REST
controller in Spring Boot.
If the Customer Information Holder, as a realization of
the
Information
Holder Resource pattern, implements the
Linked Information Holder pattern
for the customerProfile, a response message looks as
this:
GET http://localhost:8080/customers/a51a-433f-979b-24e8f0
{
"customer": {
"id": "a51a-433f-979b-24e8f0"
},
"links": [{
"rel": "customerProfile",
"href": "http://localhost:8080/customers/a51a-433f-979b-24e8f0/profile"
}, {
"rel": "moveHistory",
"href": "http://localhost:8080/customers/a51a-433f-979b-24e8f0/moveHistory"
}],
"email": "rdavenhall0@example.com",
"phoneNumber": "491 103 8336",
"customerInteractionLog": {
"contactHistory": [],
"classification": "??"
}
}The customerProfile can then be retrieved by a
subsequent GET request to the provided URI link. The
moveHistory has been factored out as well, so the pattern
is applied twice in this example.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
Many public Web APIs apply this pattern, for instance the JIRA Cloud REST API when reporting the links between issues in the “Get issue link” call.
Certain calls in the Microsoft Graph API also apply this pattern: for instance, user resource representations contain scalar and complex attributes as “Properties”, but also link to other resources such as Calendar (under “Relationships”).
RESTful HTTP APIs on maturity level 3 apply this pattern if the links representing application state transfers deal with both master data and transactional data resources and their representations. An example is Spring Restbucks.
More Information
Related Patterns
The sibling pattern Embedded Entity provides an alternative to Linked Information Holder, transmitting related data rather than referencing it.
Linked Information Holders typically reference Information Holder Resources. The referenced Information Holder Resources can be combined with Link Lookup Resource to cope with potentially broken links. By definition, Operational Data Holders reference Master Data Holders; these references can either be included and flattened as Embedded Entities or structured and then progressively followed using Linked Information Holders.
Linked Service is a similar pattern in Daigneau (2011), but less focused on data. “Web Service Patterns” Monday (2003) has a Partial DTO Population pattern which solves a similar problem.
Other Sources
See Section 7.4 in Sturgeon (2016) for additional advice and examples, to be found under “Compound Document (Sideloading)”.
The Backup, Availability, Consistency (BAC) theorem investigates data management issues further Pardon, Pautasso, and Zimmermann (2018).
References
This pattern context is similar to that of Embedded Entity, but emphasizes the diversity of client wants and needs.↩︎