- Option 1: Pagination
- Options 2 and 3: Wish List, Wish Template
- Options 4 and 5: Conditional Request, Request Bundle
- Decision Drivers and Tradeoffs
From the book
From the book
From the book
Decision Drivers and Tradeoffs
When deciding on one or more of the response shaping patterns, a primary decision driver concerns the individual information needs of clients, which have to be analyzed to find out which of the patterns are applicable and promise to have enough benefits. The currently trending GraphQL technology can be seen as an extreme form of declarative WISH TEMPLATE.
Consider situations where data transfer over the network is perceived as a potential bottleneck. In such cases, data parsimony can drive the decision. Data parsimony is an essential general design principle in distributed systems, and the five patterns can help achieve parsimonious ways of data transmission.
Security can be a driver not to apply the patterns WISH LIST and WISH TEMPLATE. Enabling clients to provide options regarding which data to receive may unwittingly expose sensitive data to unexpected requests or open up additional attack vectors. For instance, sending long data element lists or using invalid attribute names might introduce an API-specific form of denial-of-service attack. Data that is not transferred cannot be stolen and cannot be tampered with.
Finally, enhancing and, as a result, complicating an API—as all five patterns do to some extent—increases the complexity of API client and provider programming. Exceptional invocation cases introduced by the patterns require more testing and maintenance efforts.
In conclusion, no data transfer reduction might be possible or required for certain API operations. If it makes sense, however, unnecessary data transfer can be avoided through one of the two patterns WISH LIST and WISH TEMPLATE. Both of these patterns inform the provider about required data at runtime. Other alternatives are CONDITIONAL REQUESTS to avoid repeated responses to the exact requests and REQUEST BUNDLES to aggregate multiple requests in a single message. These patterns can be combined with either WISH LIST or WISH TEMPLATE. The combination of CONDITIONAL REQUEST with a WISH LIST or a WISH TEMPLATE is helpful for indicating which subset of resources is requested in case the condition evaluation states that the resource should be sent again. REQUEST BUNDLE can, in principle, be combined with each of the prior alternatives such as CONDITIONAL REQUEST, WISH LIST, or WISH TEMPLATE.
Architectural Decisions and API Patterns in our Book
Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges features these five patterns and 39 more. These patterns are organized into themes and categories, which is shown in the following figure:
Click to view full-sized image
The book features an introduction to API fundamentals, a domain model for APIs, and a decision model identifying pattern selection questions, options, and criteria; six narratives with 29 recurring decisions guide through the conceptual level of API design. The book also applies the patterns to three sample cases. A cheat sheet suggesting patterns by design issue and/or design smell is included as well.