27 Request validation

 

This chapter covers

  • Why some API methods should support pre-request validation
  • How to manage interactions with external dependencies for validation requests
  • Addressing special side effects for methods in validation requests

APIs can be confusing. Sometimes they can be confusing to the point where it’s unclear what a result will be for a given API call. For safe methods, we have a simple solution to figure out the result: just give it a try. For unsafe methods, though, that solution will obviously not work. In this pattern, we’ll explore a special validateOnly field we can add to request interfaces, which will act as a mechanism by which we can see what would have happened if the request was executed, without actually executing the request.

27.1 Motivation

Even the most straightforward APIs can be somewhat confusing—after all, APIs are complicated (otherwise there wouldn’t be a book like this). And no matter how many times we read the documentation, double-check our source code, investigate the permissions granted to us, and review the outbound requests we’re about to send to an API, we very rarely get everything right on the first attempt. Perhaps on the next attempt. Or the one after that. The key point is that there will be many attempts and it’s okay if some of them don’t succeed, or do succeed but in the wrong way.

27.2 Overview

27.3 Implementation

27.3.1 External dependencies

27.3.2 Special side effects

27.3.3 Final API definition

27.4 Trade-offs

27.5 Exercises

Summary