Pattern: Wish Template

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?


The final version of this pattern is featured in our book Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges.

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 field parameter 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.

References

Brandner, Michael, Michael Craes, Frank Oellermann, and Olaf Zimmermann. 2004. “Web Services-Oriented Architecture in Production in the Finance Industry.” Informatik-Spektrum 27 (2): 136–45. https://doi.org/10.1007/s00287-004-0380-2.
Hartig, Olaf, and Jorge Pérez. 2018. “Semantics and Complexity of GraphQL.” In Proc. World Wide Web Conference (WWW), 1155–64. https://doi.org/10.1145/3178876.3186014.


  1. Note that this problem is very similar to the problem of the pattern Wish List.↩︎