HPC API Documentation

Version 0.0.1 - October, 2019

REST API for submitting jobs to the FRCE batch cluster. The package was provided by the Biowulf team and was written for a specific application. Some useful functionality may not be present.

Prerequisites

To submit an API job, you must have a valid FRCE account and a valid Kerberos ticket. To check your Kerberos ticket status on a Linux or Mac based machine, you can run the klist command, e.g.::

$ klist
Ticket cache: FILE:/tmp/krb5cc_1000_XBAYYI
Default principal: onealdw@NIH.GOV
  Valid starting       Expires              Service principal
  10/21/2019 22:38:02  10/22/2019 08:38:02  krbtgt/NIH.GOV@NIH.GOV
  	renew until 10/28/2019 22:38:02
  10/21/2019 22:46:41  10/22/2019 08:38:02  HTTP/hpcapi.ncifcrf.gov@NIH.GOV
	renew until 10/28/2019 22:38:02

Note that the HTTP service ticket for hpcjobapi will not appear until you actually submit an API call. All you need is the ticket granting ticket (TGT).

Job submission API methods

Submit batch job

• URL: hpcapi/submit_job
• Method: POST

Request
Content-type: application/json

JSON Parameters:

• script-body (MANDATORY): the batch script (including the shebang line) to be submitted
• partition (MANDATORY): name of the partition to which the job will be submitted
• ntasks: number of tasks (equivalent to the --ntasks parameter in SlURM).
• ntasks-per-core: number of tasks per core (1 or 2 - equivalent to --ntasks-per-core in SLURM)
• ntasks-per-node: number of tasks per core (equivalent to --ntasks-per-node in SLURM)
• cpus-per-task: number of CPUs per task (equivalent to --cpus-per-task in SLURM)
• mem-per-cpu: amount of memory per CPU (equivalent to --mem-per-cpu in SLURM)
• mem-per-node: amount of memory per node (equivalent to --mem in SLURM)
• dependency: a string representing a valid SLURM job dependency
• timelimit: a valid SLURM job runtime in the form DD-HH:MM:SS (other formats to be supported later)

Notes on the request:

• The batch script must not contain any #SBATCH lines; they will be stripped out.
• Not all partitions currently may receive API jobs. Contact the FRCE administrators for the most recent list.

Response

Content-type: text/plain (severe error) or application/json
JSON parameters:

• Status: "call success" or "call failure"
• Reason: If the call is successful, the job ID is given, otherwise the reason for failure is given.

Errors:

• postdata_parse_error: The JSON in the POST could not be processed
• postdata_too_big: the POST (including the job script) is bigger than 4 KB.
• no_partition_given: the mandatory “partition” parameter was not set
• bad_partition: the partition given is not valid for API job submission
• bad_number_of_tasks: the number of tasks given is not valid
• conflicting_mem_specifications: both mem-per-cpu and mem-per-node were given
• backend_query_malloc_failed: there was a memory allocation during back-end processing to submit the job
• backend_query_job_submission_failed: there was an error submitting the job to SLURM.

OTHER ERRORS REMAIN TO BE DOCUMENTED!

Example call

$ curl -X POST -H 'Content-Type: application/json' -i --negotiate -u : \
  https://hpcapi.ncifcrf.gov/hpcapi/submit_job \
  -d '{"partition": "norm", "script-body": "#!/bin/bash\necho Hi from the API\nsleep 180\n"}'
HTTP/1.1 401 Unauthorized
Date: Mon, 27 Jan 2025 19:27:27 GMT
Server: Apache
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
WWW-Authenticate: Negotiate
Content-Length: 503
Content-Type: text/html; charset=iso-8859-1
HTTP/1.1 200 Success
Date: Mon, 27 Jan 2025 19:27:27 GMT
Server: Apache
WWW-Authenticate: Negotiate redacted
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
Content-Length: 48
Access-Control-Allow-Origin: *
Content-Type: application/json
{"status": "call_success", "reason": "46185772"}

Job Query API methods

Query Status

• URL: hpcapi/query_status
• Method: GET

Request
Content-type: None

No parameters should be passed. The system will return records for all jobs for the authenticated user over the previous 24 hours.

Response

Content-Type: text/plain (severe error) or application/json

JSON fields in response:
status: either “call_success” or “call_failure”

Example call

$ curl -X GET -i --negotiate -u : -s https://hpcapi.ncifcrf.gov/hpcapi/query_status | grep "^{" | jq

{
  "status": "call_success",
  "46186373": {
    "user": "onealdw",
    "name": "onealdw-",
    "partition": "norm",
    "start": "2025-01-27T15:24:32",
    "end": "2025-02-01T15:24:32",
    "state": "RUNNING"
  },
  "reason": "query_success"
}