Pattern Sections
Pattern: Wish Template 
a.k.a. Wish Skeleton, Response Mock, Attribute/Entity/Representation Stencil
Context
An API provider has to serve multiple different clients that invoke the same operations. Not all clients have the same information needs: some might just need a subset of the data offered by the endpoint, other clients might need rich, deeply structured data sets.
Problem
How can an API client inform the API provider about nested data that it is interested in? How can such preferences be expressed flexibly and dynamically?1
Forces
The same forces as for the Wish List pattern apply for Wish Template:
- Performance, scalability, and resource use
- Information needs of individual clients
- Loose coupling and interoperability
- Developer convenience and experience
- Security and data privacy
- Test and maintenance effort
Pattern forces are explained in depth in the book.
Solution
Add one or more additional parameters to the request message that mirror the hierarchical structure of the parameters in the corresponding response message. Make these parameters optional or use Boolean as their types so that their values indicate whether or not a parameter should be included.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
The following service contract sketch introduces a
<<Wish_Template>> highlighted with a
stereotype:
data type PersonalData P // unspecified, placeholder
data type Address P // unspecified, placeholder
data type CustomerEntity <<Entity>> {PersonalData?, Address?}
endpoint type CustomerInformationHolderService
exposes
operation getCustomerAttributes
expecting payload {
"requestPayload":D, // some in parameters
<<Wish_Template>>"mockObject":CustomerEntity
// has same structure as desired result set
}
delivering payload CustomerEntity* 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
- The Dynamic Interface described in Brandner et al. (2004) uses template objects rendered as XML documents. The structure of the wish template objects mirrors that of the responses; at runtime, a sample exemplar filled with dummy values expresses the wishes about the attributes of domain model elements such as banking customers and their accounts. Absence of optional values and empty strings express lack of interest (“don’t care”).
- The Google
Calendar API has the notion of partial requests, partial responses
and patches. This can be seen as a mix of this Wish Template
pattern (because it is possible to structure the list) and its sibling
Wish
List pattern (because the client sends a
fieldparameter that lists desired values). The syntax of the Wish Template, documented under “Fields parameter syntax summary”, is “loosely based” on XPath. - The Facebook Graph API uses this pattern.
GraphQL, also from Facebook originally and later open sourced, with its type system and its introspection and validation capabilities can be seen as an advanced or alternative realization of this pattern; the template actually is a declarative description of the information need of the client. Note that an adoption of GraphQL requires the implementation of a GraphQL server, a special type of API endpoint on top of the actual API endpoints (e.g., RESTful HTTP resources). Apollo, for instance, works with data graphs.
More Information
Related Patterns
Wish List addresses the same problem, but uses a flat enumeration rather than a mock object; both these patterns deal with instances of Parameter Tree and Parameter Forest in response messages. The Wish Template becomes part of a Parameter Tree that appears in the request message.
Using a Wish Template has a positive influence on a Rate Limit, as less data is transferred when the pattern is used and fewer requests are required.