Web services for remote job submission

This document describes remote interfaces for remotely submitting jobs and batches of jobs to a BOINC server. The APIs are accessed by sending a POST request, using HTTPS, to PROJECT_URL/job_control.php

The inputs and outputs of each API are XML documents. If an operation fails, the output is of the form

<error>
   <message>X</message>
</error>

where X is an error message.

All operations include the authenticator of the user making the request. This user must be marked as a "job submitter" in the BOINC database.

Describing a batch

A job is described by

<job>
   [<command_line>C</command_line>]
   [<input_file>URL or path</input_file>]
   ... other input files
</job>

Each input file is specified by either a URL accessible to the server, or by a path on the server.

A batch of jobs is described by:

<batch>
   <app>appname</app>
   [<input_template>x</input_template>]
   [<output_template>x</output_template>]
   <job>...</job>
   ... more jobs
</batch>

The names of the input and output template files may be specified; otherwise the defaults appname_in and appname_out are used.

Batch runtime estimation

Estimates the completion time of a batch. Input:

<batch_estimate>
   <authenticator>X</authenticator>
   <batch> ... </batch>
   [<priority>N</priority>]
</batch_estimate>

Priority, if specified, is relative to other batches submitted by this user.

Output:

<estimate>
   <seconds>X</seconds>
</estimate>

Submitting a batch

Input:

<batch_submit>
   <authenticator>X</authenticator>
   <batch> ... </batch>
   [<priority>N</priority>]
</batch_submit>

Output:

<batch_id>N</batch_id>

Querying jobs

The jobs in a batch are numbered starting from 0. The name of a job is batch_ID_N where ID is the batch ID and N is the number of the job.

Input:

<query_job>
   <authenticator>X</authenticator>
   <name>X</name>
</query_job>

Output:

<job_status>
   <aborted/>
   or
   <instance>
      <unsent/>
      or
      <hostid>N</hostid>
      <userid>M</userid>
      <runtime>X</runtime>
      <fraction_done>X</fraction_done>
   </instance>
   ... other instances
</job_status>

Querying batches

Input:

<query_batch>
   <authenticator>X</authenticator>
   <batch_id>N</batch_id>
</query_batch>

Output:

<batch_status>
   <fraction_done>X</fraction_done>
   <jobs_completed>N</jobs_completed>
   <remaining_time>X</remaining_time>
</batch_status>

Aborting jobs

Input:

<abort_batch>
   <authenticator>X</authenticator>
   <batch_id>N</batch_id>
</abort_batch>

Output:

<aborted/>

Example usage

PHP:

$ch = curl_init("http://project.edu/job_control.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURL_POSTFIELDS, "
   <batch_estimate>
      <batch>
         <app>myappname</app>
         <job>
             <command_line>--t ALPHA</command_line>
         </job>
      </batch>
   </batch_estimate>
");
$reply = curl_exec($ch);
$r = new SimpleXMLElement($reply);
curl_close($ch);

if ($r->estimate) {
   echo "Estimate: $r->estimate->seconds seconds\n";
} else {
   echo "Error: $r->error->message\n";
}
  

== Implementation notes ==