Option 2: Referenced Data
Another alternative is to make the reference data accessible remotely and reference it, introducing aLINK ELEMENTto the message:
Pattern:LINKED INFORMATION HOLDER | |
Problem | 消息怎么能让小即使一个API德als with multiple information elements referencing each other? |
Solution | Add aLINK ELEMENTto messages that pertain to multiple related information elements. Let thisLINK ELEMENTreference another API endpoint that represents the linked element. |
The two-part message exchange resulting from applying theLINKED INFORMATION HOLDERpattern is sketched in the following figure:
Click to view full-sized image
The application ofLINKED INFORMATION HOLDERleads 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
性能和可伸缩性经常扮演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 ENTITYdata 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 useEMBEDDED ENTITYmight 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 HOLDERis 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, whenMASTER DATA HOLDERSsuch as customer profile managers or product record stores are referenced fromOPERATIONAL DATA HOLDERSsuch as customer inquiry agencies or order repositories. Following links toLINKED 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 patternsDATA ELEMENTandLINK ELEMENT, which describe essential element roles in an API. In particular,LINKED INFORMATION HOLDERSuseLINK ELEMENTS, whereasEMBEDDED ENTITIESuseDATA ELEMENTS.
It is possible to combine the two patterns, for instance, when defining a top-levelEMBEDDED ENTITYthat containsLINKED INFORMATION HOLDERSfor (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.