1type: google.api.Service 2config_version: 3 3name: longrunning.googleapis.com 4title: Long Running Operations API 5 6apis: 7- name: google.longrunning.Operations 8 9types: 10- name: google.longrunning.OperationInfo 11 12documentation: 13 overview: |- 14 # Long Running Operation API 15 16 This package contains the definition of Long Running Operation (LRO) 17 interface. It is a standard interface that API services can implement for 18 managing asynchronous operations. 19 20 21 ## What are Long Running Operations? 22 23 A Long Running Operation (LRO) is a way of representing an action that may 24 take a significant amount of time to complete. For example, an API call 25 that starts exporting a large amount of data could take quite a while to 26 complete and is therefore best represented as an LRO. A common rule of 27 thumb is to think of LROs as "API promises" that represent the result of 28 some on-going action. 29 30 For more information, see [AIP-151](https://google.aip.dev/151). 31 32 ## Using LROs 33 34 If an API method could potentially take long time to finish, the method 35 should return a long running operation instead of a direct response. This 36 means that even if there are situations where the response could be 37 immediate, the API should still return an LRO -- it just may be already 38 marked as completed. 39 For example, if a data export operation is called on an empty resource, 40 the operation itself may be possible to execute immediately, and would 41 result in an already completed LRO. 42 43 Additionally, the operation should be managed using the LRO interface, 44 which allows clients to poll the operation for status updates or cancel it 45 entirely. 46 47 Finally, an LRO represents an action and as a result, the operation is not 48 created directly. Instead, the operation comes into existence as a 49 side-effect of the action it represents. For example, an RPC called 50 `ExportData` would 51 create and return an LRO. This means that there should never be an RPC 52 called `CreateOperation`. 53 54 This also means that any permissions on the operation would be based on 55 the action it represents. Any immediate side effects of starting the 56 operation must be visible in the service as soon as the LRO is returned. 57 For example, if an LRO is returned when creating a resource, that resource 58 should be visible in the API immediately, but be in a non-final state 59 until the LRO is completed. 60 61 ## LROs versus Jobs 62 63 A [job](https://google.aip.dev/152) is a common design pattern often used 64 in data processing that tends to be used to represent some contained piece 65 of work that would be stored, re-run, and modified over time. Jobs also 66 typically 67 interact with multiple resources and are created, deleted, and updated 68 directly as independent resources. 69 70 Jobs can also offer support for more complex actions such as pausing and 71 resuming an individual job, where each action could return an LRO as a 72 response. 73 74 In general, if an action may take a while but it represents a single piece 75 of work, it's best to represent the response as an LRO. If the action is 76 something more complex (for example, it involves lots of resources and 77 can't be created as a byproduct of a single action), it may make more 78 sense to represent it as a job. 79