- Option 1: Pagination
- Options 2 and 3: Wish List, Wish Template
- Options 4 and 5: Conditional Request, Request Bundle
- Decision Drivers and Tradeoffs
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 declarativeWISH TEMPLATE.
考虑n情况下数据传输etwork 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 patternsWISH LISTandWISH 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 patternsWISH LISTandWISH TEMPLATE. Both of these patterns inform the provider about required data at runtime. Other alternatives areCONDITIONAL REQUESTSto avoid repeated responses to the exact requests and请求包to aggregate multiple requests in a single message. These patterns can be combined with eitherWISH LISTorWISH TEMPLATE. The combination ofCONDITIONAL REQUESTwith aWISH LISTor aWISH TEMPLATEis helpful for indicating which subset of resources is requested in case the condition evaluation states that the resource should be sent again.REQUEST BUNDLEcan, in principle, be combined with each of the prior alternatives such asCONDITIONAL REQUEST,WISH LIST, orWISH TEMPLATE.
Architectural Decisions and API Patterns in our Book
Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchangesfeatures 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.