Pattern Sections
Pattern: Link Lookup
Resource 
a.k.a. Address Data Holder, API Directory, Endpoint Repository, Inventory/Discovery Resource, Service Registry
Context
The message representations in request and response messages of an API operation must satisfy the information needs of the message receivers entirely. To do so, these messages may contain references to other API endpoints. Sometimes, it is not desirable to expose such endpoint references to all clients directly because such direct exposure adds coupling (thus harming location and reference autonomy).
Two reasons to avoid an address coupling between communication participants are:
- As an API provider, I want to be able to change the destinations of links freely when evolving API while workload grows and requirements change.
- As an API client, I do not want to have to change code and configuration (e.g., application startup procedures) when the naming and structuring conventions for links change on the provider side.
Problem
How can message representations refer to other, possibly many and frequently changing, API endpoints and operations without binding the message recipient to the actual addresses of these endpoints?
Forces
When structuring an API that deals with linked resources and data (in the broadest sense of these words), conflicting concerns exist:
- Coupling between clients and endpoints
- Dynamic endpoint references
- Centralization vs. decentralization
- Message sizes, number of calls, resource use
- Dealing with broken links
- Number of endpoints and API complexity
Pattern forces are explained in depth in the book.
Solution
Introduce a special type of Information Holder Resource, a dedicated Link Lookup Resource endpoint that exposes special Retrieval Operation operations that return single instances or collections of Link Elements that represent the current addresses of the referenced API endpoints.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
In the Lakeside Mutual sample application, we can define two operations to find Information Holder Resources that represent customers (notation: Microservice Domain-Specific Language (MDSL), a new style- and technology-independent service contract modeling language Kapferer and Zimmermann (2020)):
API description MAPLinkLookupResource
data type URI P // protocol, domain, path, parameters
endpoint type LinkLookupResourceInterface // sketch
exposes
operation lookupInformationHolderByLogicalName
expecting payload
<<Identifier_Element>> "name": ID
delivering payload
<<Link_Element>> "endpointAddress": URI
operation lookupInformationHolderByCriteria
expecting payload {
"filter": P
}
delivering payload {
<<Link_Element>> "uri": URI* // 0..m cardinality
}
API provider CustomerLookupResource
offers LinkLookupResourceInterfaceIf multiple results of the same type are returned, the Link Lookup Resource turns into a Collection Resource Allamaraju (2010).
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
Instances of Link Lookup Resource can be found in public Web APIs and sample applications:
- The
Cargo Repositoryin the Cargo Aggregate of the Domain-Driven Design Sample Application implements two basic find operations. - Slack, which discloses an elaborate OpenAPI contract for its endpoints and operations, has the notion of object types which can be seen as pattern instances (if exposed as API endpoints).
Terravis Berli, Lübke, and Möckli (2014) internally offers and utilizes a lookup service that returns concrete API endpoints for given banks, notaries, and land registries. All these parties are referred to by a so-called Business Partner Identifier (BPID), which can be sent to the lookup service which then returns all known API endpoints offered by the identified partner.
Terravis also requires all parties to offer a service endpoint that returns a list of all supported APIs with their respective versions as a Version Identifier, as well as the actual endpoint. Terravis will query this service daily and cache the offered API versions and endpoints for use throughout the day.
Web Service Inspection Language (WSIL) support in SOAP-based Web services endpoints and Universal Description, Discovery, and Integration (UDDI) APIs can be seen as obsolete implementations and known uses of Link Lookup Resource concepts.
More Information
Related Patterns
Instances of this pattern can return links to any of the endpoint types/roles, often to Information Holder Resources.
The pattern can be combined with Retrieval Operations (on operation level). For instance, a Retrieval Operation instances may return Id Elements pointing at Information Holder Resources indirectly (that in turn return the data); the Link Lookup Resource turns the Id Element into a Link Elements.
The Collection Resource recipe 2.3 in the RESTful Web Services Cookbook Allamaraju (2010) can be seen as a RESTful HTTP pendant of this pattern, adding add and remove support; Chapter 14 then discusses discovery.
This pattern is an API-specific version/refinement of the more general Lookup pattern described in Kircher and Jain (2004) and Voelter, Kircher, and Zdun (2004). At a more abstract level, the pattern also is a specialization of the Repository pattern described in Evans (2003).
Other Sources
SOA books cover related concepts such as service repositories and registries. In Responsibility-Driven Design (RDD) terms, a Link Lookup Resource acts as a structurer Wirfs-Brock and McKean (2002).