README.md
1## Long-running Operations API
2
3This package contains the definition of an abstract interface that
4manages long running operations with API services.
5
6### Operation
7
8The primary message to understand within LRO is the `Operation` message.
9Operations have a unique name (in the context of a particular endpoint).
10Additionally, a service (called `Operations` -- plural) defines the interface
11for querying the state of any given operation.
12
13APIs that implement a concept of long-running operations are encouraged
14to follow this pattern: When a caller invokes an API backend to start a job...
15
16 * The API backend starts asychronous work to fulfill the caller's
17 request, and generates a unique name (the `Operation` name) to refer
18 to the ongoing asychronous work.
19 * The API backend immediately returns the `Operation` back to the caller.
20 * The caller can invoke the API methods defined in the `Operations` service
21 to get the current status of the asychronous work, and also to
22 discover the final result (success or error).
23
24For Google APIs, the implementation of this pattern and the use of this
25proto are part of our [design rules][operations-rules]. Additionally, our
26[API client tooling][gapic-generator] seeks to be intelligent about these, to
27improve the client API consumption experience. Therefore, APIs outside of
28Google can also benefit by following this same pattern.
29
30 [operations-rules]: https://cloud.google.com/apis/design/design_patterns#long_running_operations
31 [gapic-generator]: https://github.com/googleapis/gapic-generator
32