[[PageOutline]]
= API for remote job submission =

This document describes an API for remotely submitting jobs to a BOINC server.
The API supports the submission of '''batches''' of jobs.
A batch could contain a single job, or many thousands of jobs.
Currently, the API has two restrictions:

 * All jobs in a batch must use the same application.
 * There can be no dependencies between jobs.

BOINC provides a PHP library that implements the API.
The underlying web services are implemented as HTTP/XML RPCs,
and it is possible to create bindings in other languages.

The API can be used, for example, to create web interfaces for job submission,
such as might be found in a science portal web site:

[[Image(submit.png)]]

This system is coupled with BOINC's [MultiUser multi-user project features].
This includes access control:
users can submit jobs only if they have been given access by project administrators,
and admins can restrict the apps for which each user is allowed to submit jobs.

== PHP interface ==

The following functions are provided in the PHP file
[/trac/browser/trunk/boinc/html/inc/submit.inc submit.inc],
which is independent of other BOINC code and can be used in the Portal web code.

=== boinc_submit_batch() ===

Submits a batch.

Arguments: a "request object" whose fields include
 * '''project''': the project URL
 * '''authenticator''': the user's authenticator
 * '''app_name''': the name of the application for which jobs are being submitted
 * '''batch_name''': a symbolic name for the batch.  Need not be unique.
 * '''jobs''': an array of job descriptors, each of which contains
  * '''rsc_fpops_est''': an estimate of the FLOPs used by the job
  * '''command_line''': command-line arguments to the application
  * '''input_files''': an array of input file descriptors, each of which contains
   * '''source''': a URL from which the BOINC server can download the file,
     or the path of the file on the BOINC server

Result: a 2-element array containing
 * The batch ID
 * An error message (null if success)

The following example submits a 10-job batch:
{{{
$req->project = "http://foo.bar.edu/test/";
$req->authenticator = "xxx";
$req->app_name = "uppercase";
$req->jobs = array();

$f->source = "http://foo.bar.edu/index.php";
$job->input_files = array($f);

for ($i=10; $i<20; $i++) {
    $job->rsc_fpops_est = $i*1e9;
    $job->command_line = "--t $i";
    $req->jobs[] = $job;
}

list($e, $errmsg) = boinc_estimate_batch($req);
if ($errmsg) {
    echo "Error: $errmsg\n";
} else {
    echo "The batch will take about $e seconds to complete\n";
}
}}}

=== boinc_estimate_batch() ===

Returns an estimate of the elapsed time required to complete a batch.

Arguments: same as '''boinc_submit_batch()'''
(only relevant fields need to be populated).

Return value: a 2-element array containing
 * The elapsed time estimate, in seconds
 * An error message (null if success)

=== boinc_query_batches() ===

Returns a list of this user's batches, both in progress and complete.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above.

Result: a 2-element array.
The first element is an array of batch descriptor objects,
each with the following fields:
 * '''id''': batch ID
 * '''state''': values are
  * 1: in progress
  * 2: completed (all jobs either succeeded or had fatal errors)
  * 3: aborted
  * 4: retired
 * '''name''': the batch name
 * '''app_name''': the application name
 * '''create_time''': when the batch was submitted
 * '''est_completion_time''': current estimate of completion time
 * '''njobs''': the number of jobs in the batch
 * '''fraction_done''': the fraction of the batch that has been completed (0..1)
 * '''nerror_jobs''': the number of jobs that had fatal errors
 * '''completion_time''': when the batch was completed
 * '''credit_estimate''': BOINC's initial estimate of the credit that
  would be granted to complete the batch, including replication
 * '''credit_canonical''': the actual credit granted to canonical instances
 * '''credit_total''': the actual credit granted to all instances

=== boinc_query_batch() ===

Gets batch details.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above
 * '''batch_id''': specifies a batch.

Result: a 2-element array.
The first element is a batch descriptor object as described above,
with one additional field:
 * '''jobs''': an array of job descriptor objects, each one containing
  * '''id''': the database ID of the job's workunit record
  * '''canonical_instance_id''': if the job has a canonical result, its database ID

=== boinc_query_job() ===

Gets job details.

Argument: a request object with elements:
 * '''project''' and '''authenticator''': as above
 * '''job_id''': specifies a job.

Result: a 2-element array.
The first element is a job descriptor object with the following fields:
 * '''instances''': an array of job instance descriptors, each containing:
  * '''name''': the instance's name
  * '''id''': the ID of the corresponding result record
  * '''state''': a string describing the instance's state
   (unsent, in progress, complete, etc.)
  * '''outfile''': if the instance is over,
   a list of output file descriptors, each containing
   * '''size''': file size in bytes

=== boinc_abort_batch() ===

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''batch_id''': specifies a batch.

Result: an error message, null if successful

=== boinc_get_output_file() ===

Get a URL for a particular output file.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''instance_name''': specifies a job instance,
 * '''file_num''': the ordinal number of one of the output files.

Result: a URL from which the output file can be downloaded.

=== boinc_get_output_files() ===

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''batch_id''': specifies a batch.

Result: a URL from which a zipped archive of all
output files from the batch can be downloaded
(only the outputs of "canonical" instances are included).

=== boinc_cleanup_batch() ===

Delete server storage (files, DB records) associated with a batch.

Argument: a request object with elements
 * '''project''' and '''authenticator''': as above,
 * '''batch_id''': specifies a batch.

Result: an error message, null if successful

== HTTPS/XML interface ==

At a lower level, the APIs are accessed by sending a POST request,
using HTTPS, to PROJECT_URL/submit.php.
The inputs and outputs of each function are XML documents.
The format of the request and reply XML documents
can be inferred from inc/submit.inc and user/submit.php.

Bindings of these RPCs can be implemented in languages other than PHP.