From the author of
From the author of
From the author of
Option 2: Referenced Data
Another alternative is to make the reference data accessible remotely and reference it, introducing a LINK ELEMENT to the message:
| Pattern: LINKED INFORMATION HOLDER | |
| Problem | How can messages be kept small even when an API deals with multiple information elements referencing each other? |
| 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. |
The two-part message exchange resulting from applying the LINKED INFORMATION HOLDER pattern is sketched in the following figure:
Click to view full-sized image
The application of LINKED INFORMATION HOLDER leads to smaller messages that can refer to other API resources and, therefore, will lead to multiple round-trips to retrieve the same information. In the book, we discuss many more details, for instance how to deal with 1:n and n:m relationships in the API design.
Decision Drivers and Tradeoffs
Performance and scalability often play a significant role when deciding between these two patterns. Both message size and the number of calls required to perform an integration should be small, but these two desires conflict with each other. Modifiability and flexibility also have to be considered: information elements contained in structured self-contained data might be hard to change because any implementation-internal updates have to be coordinated and synchronized with updates to related request/response message structures and the API operations that send and receive them. Structured data that contains references to external resources usually is even harder to change than self-contained data as there are more consequences and (external) dependencies for clients.
EMBEDDED ENTITY data sometimes gets stored on the receiver side for a while, whereas links always refer to the latest version of data. Thus, accessing data on demand via links is positive for data quality, freshness, and consistency. Regarding data privacy, a link source and target might have different protection needs—for example, a person and the credit card information belonging to this person. This has to be considered, for instance, before embedding the credit card information in a message requesting the person's data.
The decision to use EMBEDDED ENTITY might depend on the number of message consumers and the homogeneity of their use cases. For example, if only one consumer with a specific use case is targeted, it is often good to embed all necessary data immediately. In contrast, different consumers might not work with the same data. To minimize message sizes, it might be advisable not to transfer all data all the time. The same organization might develop both client and provider. Embedding entities can be a reasonable strategy to minimize the number of requests in that case. In such a setting, they simplify development by introducing a uniform regular structure.
LINKED INFORMATION HOLDER is well suited when referencing rich information holders serving multiple usage scenarios: usually, not all message recipients require the complete set of referenced data, for instance, when MASTER DATA HOLDERS such as customer profile managers or product record stores are referenced from OPERATIONAL DATA HOLDERS such as customer inquiry agencies or order repositories. Following links to LINKED INFORMATION HOLDERS, message recipients can obtain the required subsets on demand.
There are several other relations between the patterns. They are related to the basic structural patterns DATA ELEMENT and LINK ELEMENT, which describe essential element roles in an API. In particular, LINKED INFORMATION HOLDERS use LINK ELEMENTS, whereas EMBEDDED ENTITIES use DATA ELEMENTS.
It is possible to combine the two patterns, for instance, when defining a top-level EMBEDDED ENTITY that contains LINKED INFORMATION HOLDERS for (some of) its referenced data records. Combining linking and embedding data often make sense, for instance, embedding all data immediately displayed in a user interface and linking the rest for retrieval upon demand. The linked data is fetched only when the user scrolls or opens the corresponding user interface elements.