This chapter covers
- How to use long-running operations for non-immediate API calls
- Storing metadata about operational progress
- Where operations should live in the resource hierarchy
- Finding operation status (including error results) via polling and blocking
- Interacting with running operations (e.g., pausing, resuming, and canceling)
In most cases, incoming requests can be processed quickly, generating a response within a few hundred milliseconds after the request is received. In the cases where responses take significantly longer, the default behavior of using the same API structure and asking users to “just wait longer” is not a very elegant option. In this chapter, we’ll explore how to use long-running operations as a way of allowing API methods to behave in an asynchronous manner and ensuring that the slower API methods (including standard methods we saw in chapter 7) can provide quick and consistent feedback while executing the actual work in the background.
So far, all of the API methods we’ve explored have been immediate and synchronous. The service receives a request, does some work right away, and sends back a response. And this particular manner of behavior is actually hardcoded into the API design as the return type is the result, not some promise to return a result later on down the line.