AIP-152

Jobs

Occasionally, APIs may need to expose a task that takes significant time to complete, and where a transient long-running operation is not appropriate. For example, a task could need to run repeatedly, or have separate permissions for configuring the task as opposed to running it.

Guidance

An API may define a Job resource to represent a particular task with distinct setup, configuration, and execution:

message WriteBookJob {
  // The resource name for the writing job.
  string name = 1 [(google.api.resource) = {
    type: "library.googleapis.com/WriteBookJob"
    pattern: "publishers/{publisher}/writeBookJobs/{write_book_job}"
  }];

  // Additional configuration...
}
  • The name of the resource must end with the word “Job”.
    • The prefix should be a valid RPC name, with a verb and a noun.
  • The service should define all five of the standard methods (AIP-131, AIP-132, AIP-133, AIP-134, AIP-135), and use them as the primary way to configure the job.

Run method

The service should define a Run custom method that executes the job immediately:

rpc RunWriteBookJob(RunWriteBookJobRequest)
    returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*/writingJobs/*}:run"
    body: "*"
  }
  option (google.longrunning.operation_info) = {
    response_type: "RunWriteBookJobResponse"
    metadata_type: "RunWriteBookJobMetadata"
  }
}
  • The HTTP method must be POST.
  • The method should return a long-running operation, which must resolve to a response message that includes the result of running the job.
    • The method may use any metadata message it wishes.
  • Errors that prevent execution of the job from starting must return an error response (AIP-193), similar to any other method. Errors that occur over the course of the job execution may be placed in the metadata message. The errors themselves must still be represented with a google.rpc.Status object.

Executions and results

Ordinarily, the API should provide results to the user as the final response of the Run method. However, this is sometimes insufficient; for example, a job that runs on a recurring schedule in the background can not deliver results to the user in this way.

The service may store resources representing individual executions along with their result as a sub-collection of resources under the job, which allows the user to list past job executions. A service that does this should define the Get, List, and Delete methods for the execution resources:

message WriteBookJobExecution {
  option (google.api.resource) = {
    type: "library.googleapis.com/WriteBookJobExecution"
    pattern: "publishers/{publisher}/writeBookJobs/{write_book_job}/executions/{execution}"
  };

  string name = 1;

  // Other information about the execution, such as metadata, the result,
  // error information, etc.
}

In this case, the operation returned by job’s Run method should refer to the child resource.