The CANFAR Processing Web Service

This service provides a RESTful web service interface to the CANFAR condor processing system.

Resources

Getting Access to The CANFAR Processing Web Service

To receive access to The CANFAR Processing Web Service, users must request a home directory from CANFAR. Please go to CANFAR (www.canfar.net) to gain access.

Usage

HTTP POST

HTTP POST action is used to submit jobs to condor. The syntax for posting jobs has four required parameters:

• job - the job submission file
• exec - the job executable
• image - URI of the virtual machine image
• flavor - URI of the flavor (describing processing resources required)

Syntax:

https://www.canfar.phys.uvic.ca/proc/job?job=<name>,<uri>&exec=<name>,<uri>&image=vmi:<image uuid>&flavor=fli:<flavor uuid>

Where:
    <name> is the name of the parameter (content will be saved as this name)
    <uri> refers to the location of the parameter data. uri can be one of:
        vos: for a vospace file
        param: inline data on the post
        vm: on the vm (applicable to parameter exec only)
    <image URI> in the format vmi:UUID (UUID is obtained through the openstack glance client)
    <flavor URI> in the format fli:UUID (UUID is obtained through the openstack nova client)

Example 1: Submit a job where both the submission file and executable are in the POST as multi-part inline data:

curl -E <cert.pem> -X POST -F "job_sub=<job submission file contents>" -F "exec_ls=/bin/ls" "https://www.canfar.phys.uvic.ca/proc/job?job=jobFile,param:job_sub&exec=execFile,param:exec_ls&image=vmi:a4728b62-d15f-4e10-8475-1481ea3037d4&flavor=fli:de7afe99-a559-4744-bab7-fbc30e85fcfc"

Example 2: Submit a job where the submission file is in the POST as multi-part inline data and the executable is in vospace directory /test/myProgram.exe:

curl -E <cert.pem> -X POST -F "job_sub=<job submission file contents>" "https://www.canfar.phys.uvic.ca/proc/job?job=jobFile,param:job_sub&exec=execFile,vos://cadc.nrc.ca~vospace/test/myProgram.exe&image=vmi:a4728b62-d15f-4e10-8475-1481ea3037d4&flavor=fli:de7afe99-a559-4744-bab7-fbc30e85fcfc"

Example 3: Submit a job where the submission file is in VOSpace directory /test/myJobSubmitFile and the executable is exists on the VM as /my/folder/myProgram.exe

curl -E <cert.pem> -X POST "https://www.canfar.phys.uvic.ca/proc/job?job=jobFile,vos://cadc.nrc.ca~vospace/test/myJobSubmitFile&exec=execFile,vm:/my/folder/myProgram.exe&image=vmi:a4728b62-d15f-4e10-8475-1481ea3037d4&flavor=fli:de7afe99-a559-4744-bab7-fbc30e85fcfc"

On the response to the HTTP POST, the job's cluster id will be returned. The cluster ID is the first segment of the job id, which is in the format:

<clusterID>.<processID>

Where processID identfies the instance of the job. processID starts at zero and goes up by one for every instance.

HTTP GET

HTTP GET action is supported. GETs to /proc/job or /proc/auth/job will result in the download of a VOTable of currently queued condor jobs. If the request parameter RESPONSEFORMAT is set to text/plain, the table will be in ASCII format with tabs separating the columns.

Example 1: See the list of queued condor jobs as a VOTable:

curl -E <cert.pem> "https://www.canfar.phys.uvic.ca/proc/job"

Example 2: Set the list of queued condor jobs in tab delimited text format:

curl -E <cert.pem> "https://www.canfar.phys.uvic.ca/proc/job?RESPONSEFORMAT=text/plain"

If the query parameter 'id' is provided in the HTTP GET call, then details about the job identified by the job ID are returned. This will only return details on jobs that have recently completed execution. For example:

curl -E <cert.pem> "https://www.canfar.phys.uvic.ca/proc/job?id=1234.0"

Will return details about the job 1234.0

If the query parameter 'status' is provided in the HTTP GET call, then information about the current state of the processing scheduler are returned. For example:

curl -E <cert.pem> "https://www.canfar.phys.uvic.ca/proc/job?status=true"

Will return information about the current state of the processing scheduler in VOTable format.

Scheduler status information can also be returned in tab delimited text format:

curl -E <cert.pem> "https://www.canfar.phys.uvic.ca/proc/job?status=true&RESPONSEFORMAT=text/plain"

HTTP DELETE

HTTP DELETE to /proc/job or /proc/auth/job will DELETE all jobs owned by the user executing HTTP DELETE.

Example: Delete all jobs owned by the user identified in <cert.pem>:

curl -E <cert.pem> -X DELETE "https://www.canfar.phys.uvic.ca/proc/job"

Response Codes

Standard response codes:
- 400 (bad request) if the request Content-Type is not multipart/form-data,
- 400 (bad request) if the job submission file cannot be interpreted,
- 403 (forbidden) if the caller does not provide a authentication credentials,
- 403 (forbidden) if the caller does not have permission to submit jobs,
- 404 (not found) if job information specified by parameter 'id' could not be found,
- 405 (method not allowed) if the request method is not supported.
- 500 (internal error) if the server experiences an unrecoverable error.
- 503 (busy) if the server is too busy to process the request.