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/*/writeBookJobs/*}:run"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "RunWriteBookJobResponse"
    metadata_type: "RunWriteBookJobMetadata"
  };
}
  • The RPC's name must begin with the word Run. The remainder of the RPC name should be the singular form of the job resource being run.
  • The request message must match the RPC name, with a Request suffix.
  • The method should return a long-running operation, which must resolve to a response message that includes the result of running the job.
    • The response message name must match the RPC name, with a Response suffix.
    • The method may use any metadata message it wishes.
  • The HTTP verb must be POST, as is usual for custom methods.
  • The body clause in the google.api.http annotation should be "*".
  • The URI path should contain a single name variable corresponding to the name of the job resource being run.
  • The URI path must end with :run.
  • 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.

Run request message

Run methods implement a common request message pattern:

message RunWriteBookJobRequest {
  // The name of the job to run.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/WriteBookJob"
    }];
}

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.

Changelog

  • 2022-06-02: Changed suffix descriptions to eliminate superfluous "-".
  • 2020-11-02: Expanded guidance on HTTP, field behavior, and resource reference annotations and request format.