Overview
The JARVICE API allows full control on running jobs as well as managing applications via PushToCompute™. The API server delivers the endpoints below - for the Nimbix Public Cloud the API server is:
https://api.jarvice.com/
Unless otherwise noted, all endpoints support both GET and POST request methods. Also, unless otherwise noted, responses deliver both an HTTP status code and a JSON payload.
In all cases referring to an API key, this is available from the JARVICE portal in the Account section. This is not the same as the password used to log into the portal.
Job Control
These API endpoints allow you to submit jobs and control their execution. Jobs run on one or more compute nodes and launch the image of an application from the service catalog.
/jarvice/action
Executes an application-defined command inside a running job. The command runs asynchronously and its standard output/standard error is accessible with /jarvice/tail while the job is running.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit) -
action
- the name of the action to run (must be a valid action from /jarvice/info)
Response
On success: {"status": "action requested"}
Additional Notes
-
One of
name
ornumber
must be specified -
Action is requested asynchronously - if the action produces output in a batch job, it can be checked with /jarvice/tail
/jarvice/shutdown
Requests a graceful termination of a job, executing the operating system poweroff
mechanism if applicable.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit)
Response
On success: {"status": "shutdown requested"}
A job not in PROCESSING STARTING
status will return an error, e.g. {"error": "Running job is not found"}
Additional Notes
-
One of
name
ornumber
must be specified -
Shutdown is requested asynchronously - job status can be monitored with /jarvice/status
-
Current job status must be
PROCESSING STARTING
as indicated by output of /jarvice/status, e.g.{"job_status": "PROCESSING STARTING"}
. For other states, see /jarvice/terminate
/jarvice/submit
Submits a job for processing. The body is in JSON format and can be generated from the JARVICE web portal by clicking the PREVIEW SUBMISSION tab in the task builder and copying its contents to the clipboard - e.g.:
Click the copy icon above the SUBMIT button to copy the contents of the API call to the clipboard.
NOTE: Adding the identity
object in the submission json will replace the NIMBIX Application Environment nimbix
user. The JARVICE API cannot override an identity
set by an AppDef file.
Sample identity
object:
{
"username": "hpc",
"group": "jarvice",
"uid": 1111,
"gid": 2222
}
Parameters
POST only: JSON payload to run the compute job, generated as specified above. If copying from the web portal, paste the text into a file or script to use as the JSON payload to submit. Please note that authentication is performed from the username
and apikey
values in the JSON itself.
Response
On success, a JSON payload indicating the job name and job number (with name
and number
keys).
Additional Notes
-
All boolean values default to
false
if not specified -
The
nodes
parameter in the machine section defaults to1
if not specified -
Even if a
vault
section is specified,password
is optional and should only be supplied for encrypted block vaults -
Even if
vault
section is specified, vaultobjects
is optional and applies only to object storage vaults; it indicates which objects should be moved into the environments's backing store for processing. Ifreadonly
is set tofalse
, JARVICE automatically copies any new or changed objects from the backing store back to the object storage on normal job completion (but not immediate termination with /jarvice/terminate). -
ipaddr
will be validated by the underlying platform for authorization for the user; it may also fail if the address is already assigned (but this won't be known until the job starts running).
/jarvice/terminate
Immediately terminates a running job. NB: This will terminate the job regardless of current status.
Best Practice: Use the /jarvice/shutdown for a job in PROCESSING STARTING
state and only use /jarvice/terminate for a job not in a PROCESSING STARTING
state or not responding to a /jarvice/shutdown.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit)
Response
On success: {"status": "terminated"}
Additional Notes
- One of
name
ornumber
must be specified
Status and Information
These API endpoints allow you to query status or request information from running or completed jobs.
/jarvice/appdef
Returns the Application Definition (AppDef) for a given application.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
- name of application to return information for; please note this is the application ID, not necessarily the same as thename
value in the AppDef
Response
On success, a JSON payload with the AppDef requested.
/jarvice/apps
Returns information about available application(s).
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - name of application to return information for (default, if not specified: all)
Response
On success, a JSON payload with application information for each available application, or for the specific application name if available. The application name is used as the dictionary key, and the data subkey contains the raw definition in JSON format. The price
value is the application price itself, not including underlying machine price (which is available by querying the machine type using /jarvice/machines).
Note that application name is the application ID, not necessarily the same as the human readable name
in the AppDef for the given application.
/jarvice/connect
Requests the network address and user nimbix
password (if set), for an interactive job.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit)
Response
On success, a JSON payload: {"address": <network-address>, "password": <nimbix-password>}
Additional Notes
-
One of
name
ornumber
must be specified -
Job must be running an application endpoint that has
interactive
set totrue
in its AppDef in order for it to respond successfully -
This method may take a few seconds to respond successfully after starting a job, as its connection parameters are not known until its application components start
/jarvice/info
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit)
Response
On success, a JSON payload, e.g.:
{
"url": <web-service-URL>
"about": <about-HTML>
"help": <help-HTML>
"actions": {
<action-1> {
"alt": <action-description>
},
<action-n> {
"alt": <action-description>
}
}
}
-
web-service-URL is intended to be used to connect to an application-specific web service, if one exists, running inside the application environment; the address is accessible from the client; the value is taken from
/etc/NAE/url.txt
inside the environment -
All values may be
null
if not applicable
Additional Notes
-
One of
name
ornumber
must be specified -
This method may take a few seconds to respond successfully after starting a job, as its connection parameters are not known until its application components start
/jarvice/jobs
Returns job information and status for all queued and running jobs.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
completed
(optional) - set totrue
(case sensitive) to show only completed jobs (default, if not specified:false
)
Response
On success, a JSON payload with job status for each queued or running job (keyed by job number), formatted like the response of /jarvice/status
/jarvice/machines
Returns information about available machine type(s).
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - name of machine type to return information for (default, if not specified: all)
Response
On success, a JSON payload with machine information for each available machine type, or for the specific machine name
if available. The machine name is used as the dictionary key.
/jarvice/metrics
Returns the last known CPU and memory utilization metrics for a given job.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit)
Response
On success, a JSON payload indicating summary values in the summary
key, and itemized values (one for each parallel node in the job) in the itemized
key - e.g.:
{
"itemized": {
"memory_used": [
118832,
99760
],
"cpu_used": [
52,
0
],
"memory_total": [
16777216,
16777216
]
},
"summary": {
"memory_used": 218592,
"cpu_used": 26,
"memory_total": 33554432
}
}
Additional Notes
- One of
name
ornumber
must be specified cpu_used
is always a percentage value (percentage of total CPU resource allocated), whilememory_used
andmemory_total
are always in kilobytes.- In the summary section,
cpu_used
is the average of all CPU utilization across all nodes in the job, while the memory values are the sum total, in kilobytes. - The percentage of memory utilized from the summary can be calculated by dividing
memory_used
bymemory_total
and multiplying by100
. - All values are "point in time" rather than rolling average or any type of cumulative calculation, and are collected periodically (typically every 30 seconds)
- This endpoint may return a 404 for approximately the first minute that a job is running, until metrics become available
/jarvice/output
Returns a tail (or optionally all) of the output of a completed job.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit) -
lines
(optional) - number of lines to tail from the end (default: 100) - use0
to return all lines rather than just a tail
Response
On success, the requested output tail in text/plain format
(with single \n
for line breaks), up to and including the number of lines requested; if the total length of the output is less than lines requested, the entire output is returned. If lines requested is 0
, all lines in the output are returned rather than just a tail of it.
Additional Notes
-
One of
name
ornumber
must be specified -
Job must have completed; to get the output of a running job instead, use /jarvice/tail
/jarvice/screenshot
Returns a screenshot for a running job (if it is graphical).
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit) -
width
(optional) - pixel width to restrict screenshot to -
height
(optional) - pixel height to restrict screenshot to -
emphatic
(optional) - if specified, emphatically resize (disregarding aspect ratio) to specifiedwidth
and/orheight
Response
On success, an image/png
payload with the requested screenshot if available.
Additional Notes
-
One of
name
ornumber
must be specified -
If
emphatic
is not specified, butwidth
and/orheight
is, the aspect ratio of the screenshot image is preserved when resizing.
/jarvice/status
Queries status for a previously submitted job.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit)
Response
On success, a JSON payload with job status, formatted as follows:
{
<job-number> {
"job_name": <job-name>
"job_status": <job-status>
"job_submit_time": <job-submit-time>
"job_start_time": <job-start-time>
"job_end_time": <job-end-time>
"job_application": <job-application>
"job_command": <job-command>
"job_walltime": <job-walltime>
}
}
- All "time" values are represented in UNIX time (seconds since the Epoch); values may be 0 if the data is not yet available (e.g. a job that hasn't completed yet will have a 0 for
job_end_time
); additional values may be returned in the future.
Additional Notes
- One of
name
ornumber
must be specified
/jarvice/tail
Returns a tail (or optionally all) of the output of a running job.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
name
(optional) - job name (name key returned from /jarvice/submit) -
number
(optional) - job number (number key returned from /jarvice/submit) -
lines
(optional) - number of lines to tail from the end (default: 100) - use0
to return all lines rather than just a tail
Response
On success, the requested output tail in text/plain format
(with single \n
for line breaks), up to and including the number of lines requested; if the total length of the output is less than lines requested, the entire output is returned. If lines requested is 0
, all lines in the output are returned rather than just a tail of it.
Additional Notes
-
One of
name
ornumber
must be specified -
Job must still be running; to get the output of a completed job instead, use /jarvice/output
/jarvice/teamjobs
Returns job information and status for all queued and running jobs for an entire team.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
completed
(optional) - set totrue
(case sensitive) to show only completed jobs (default, if not specified:false
)
Response
On success, a JSON payload with job status for each queued or running job (keyed by job number), formatted like the response of /jarvice/status
Additional Notes
- If
username
does not refer to a team payer, only jobs for that user will be listed
/jarvice/teamusers
(Team Admins only) Returns a list of JARVICE users who are members of the callers team
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate
Reponse
On success, a JSON payload with a list of team members, formatted as follows:
{
<jarvice-username> : {
"email": <user-email>,
"name": <user-name>
}
}
/jarvice/billing
(JXE/System Admins only) Returns billing report for JARVICE users
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
reportuser
(optional) - comma separated list of users to filter (default, if not specified: list all users) -
billingcode
(optional) - billing code to filter by -
statuses
(optional) - comma seperated string of statuses to filter by -
machtypes
(optional) - comma seperated string of machine types to filter -
jobapp
(optional) - application name to filter by (e.g. jarvice-ubuntu) -
itemized
(optional) - set totrue
to generate itemized report (default, if not specified:false
) -
timeperiod
(optional) - includes jobs in the previous/current month or custom range (eitherlast
,current
, orrange
) -
startdate
(optional) - range start of time period to generate report (YYYY-MM-DD) -
enddate
(optional) - range end of time period to generate report (YYYY-MM-DD)
Response
On success, a CSV file containing generated billing report
Additional Notes
-
Endpoint is for JARVICE XE System Administrators only
-
If
reportuser
is a payer of a team, all team members are included -
Valid
statuses
fields are: COMPLETED, COMPLETED WITH ERROR, SUBMITTED, PROCESSING STARTING, CANCELED, EXEMPT, SEQUENTIALLY QUEUED, TERMINATED -
Valid
machtypes
can be queried using/jarvice/machines
API -
startdate
andenddate
are required iftimeperiod
is set torange
PushToCompute™
These API endpoints allow you to manage JARVICE application images via the PushToCompute™ subsystem. For more information on these mechanisms, please see CI/CD Pipeline.
/jarvice/history
Retrieve build/pull history for a JARVICE application image.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
target
- target image name to get history for (usually same as the application ID) -
limit
(optional) - the number of entries to limit the output to (default: 100) -
reltime
(optional) - use relative timestamps (default:true
) - set tofalse
to use absolute timestamps
Response
On success, the requested reverse chronological history (most recent first) in text/plain
format (with single \n
for line breaks), up to and including the limit
requested. Blank output indicates either the target does not exist, or has no associated build/pull history (yet).
/jarvice/pull
Pulls a Docker repository into a JARVICE application image. The JARVICE application image must already exist.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
repo
- Docker repository to pull from -
target
- target image name to store application in (usually same as the application ID)
Response
A JSON payload with the status message in the status
key.
Additional Notes
-
You will receive a notification once the pull starts and completes, either with or without error, per your account's notification preferences
-
repo
uses the same syntax as thedocker pull
does -
If pulling a private repository, you must log into the Docker registry in the JARVICE portal from the PushToCompute™ page first
/jarvice/build
Builds a JARVICE application image for a Docker repository. The JARVICE application ID must already exist.
Parameters
-
username
- name of user to authenticate -
apikey
- API key for user to authenticate -
target
- target application ID to build an image for (must exist) -
pull
(optional) - on successful build, pull Docker repository into a JARVICE application image (default:false
) -
abort
(optional) abort a running image build (default:false
)
Response
A JSON payload with the status message in the status
key.
Additional Notes
-
You will receive a notification once the build starts and completes, either with or without error, per your account's notification preferences
-
If
abort
is specified, any running build is aborted immediately; if not, a build is scheduled; note that scheduling a build with one already running results in failure -
abort
does not automatically schedule a new build - it merely changes the meaning of this endpoint from schedule to abort build
/jarvice/validate
Validates an AppDef (application definition).
Parameters
POST only: JSON payload containing an AppDef (application definition) to validate. Please see the Application Definition Guide for details on the format. A valid AppDef can be used to customize the user interface endpoints for an application, as well as descriptive metadata.
Response
A JSON payload with the boolean status in the valid
key if successful, or a 400 error with a descriptive message on failure.
Additional Notes
- Validation is done in a single pass and may not pinpoint the exact location of the error in every case