This AIP is currently under review. This means that the editors have read it and are in high-level concurrence, and while it is not yet fully approved, we have a good faith expectation that the AIP will be approved in something close to its current state.

AIP-151

Long-running requests

Occasionally, a service may need to expose an operation that takes a significant amount of time to complete. In these situations, it is often a poor user experience to simply block while the task runs; rather, it is better to return some kind of promise to the user, and allow the user to check back in later.

The long-running request pattern is roughly analogous to a Future in Python or Java, or a Node.js Promise. Essentially, the user is given a token that can be used to track progress and retrieve the result.

Guidance

Operations that might take a significant amount of time to complete should return a 202 Accepted response along with an identifier that can be used to track the status of the request and ultimately retrieve the result.

Any single operation defined in an API surface must either always return 202 Accepted along with a request identifier, or never do so. A service must not return a 200 OK response with the result if it is "fast enough", and 202 Accepted if it is not fast enough, because such behavior adds significant burdens for clients.

Note: User expectations can vary on what is considered "a significant amount of time" depending on what work is being done. A good rule of thumb is 10 seconds.

Status monitor representation

The response to a long-running request should be a "status monitor" having the following common format:

interface StatusMonitor {
  // The identifier for this status monitor.
  id: string;

  // Whether the request is done.
  done: boolean;

  // The result of the request.
  // Only populated if the request is done and was successful.
  response: any;

  // The error that arose from the request.
  // Only populated if the request is done and was unsuccessful.
  error: Error;

  // Metadata associated with the request.
  // Populated throughout the life of the request, including after
  // it completes.
  metadata: any;
}

• If the done field is true, then one and exactly one of the response and error fields must be populated.
  • If the done field is false, then the response and error fields must not be populated.
• The response and metadata fields may be any type that the service determines to be appropriate, but must always be the same type for any particular operation.
  • The response and metadata types should be defined in the same API surface as the operation itself.
  • The response and metadata types that need no data should use a custom-defined empty struct rather than a common void or empty type, to permit future extensibility.

Querying a status monitor

The service must provide an endpoint to query the status of the operation, which must accept the operation identifier and should not include other parameters:

GET /v1/statusMonitors/{status_monitor} HTTP/2
Host: library.googleapis.com
Accept: application/json

The endpoint must return a StatusMonitor as described above.

Standard methods

APIs may return an StatusMonitor from the Create, Update, or Delete standard methods if appropriate. In this case, the response field must be the standard and expected response type for that standard method.

When creating or deleting a resource with a long-running request, the resource should be included in List and Get calls; however, the resource should indicate that it is not usable, generally with a state enum.

Parallel requests

A resource may accept multiple requests that will work on it in parallel, but is not obligated to do so:

• Resources that accept multiple parallel requests may place them in a queue rather than work on the requests simultaneously.
• Resource that does not permit multiple requests in parallel (denying any new request until the one that is in progress finishes) must return 409 Conflict if a user attempts a parallel request, and include an error message explaining the situation.

Expiration

APIs may allow their status monitor resources to expire after sufficient time has elapsed after the request completed.

Note: A good rule of thumb for status monitor expiry is 30 days.

Errors

Errors that prevent a long-running request from starting must return an error response (AIP-193), similar to any other method.

Errors that occur over the course of a request may be placed in the metadata message. The errors themselves must still be represented with a canonical error object.

Interface Definitions

// Write a book.
rpc WriteBook(WriteBookRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:write"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "WriteBookResponse"
    metadata_type: "WriteBookMetadata"
  };
}

paths:
  /v1/resources:
    post:
      operationId: write_book
      description: Write a book.
      responses:
        202:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteBookStatus'