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 {
  option (google.api.resource) = {
    type: "library.googleapis.com/WriteBookJob"
    pattern: "publishers/{publisher}/writeBookJobs/{write_book_job}"
  };

  // Name and other fields...
}

• 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"
    }];
}

• A singular string name field must be included.
  • The field should be annotated as required.
  • The field should identify the resource type that it references.

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}"
  };

  // Name and 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.