3. WebAPI specification

Swagger WebAPI specification

POST /command/{machine}

execute specified command

execute specified command
example)
curl https://api.fugaku.r-ccs.riken.jp/command/computer/ -H "Authorization: Bearer $accessToken" -X POST -d '{"command": "mkdir -p ~/job-script; ls -ld ~/job-script"}'
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

Request JSON Object:

  • command (string) – (required)

Status Codes:
Response JSON Object:

  • error (string) – error ID (required)

  • output (string) – command output result (required)

  • status (string) – status (required)

GET /status/

get all machine state

get all machine state
Outputs the status of all machines managed by the server.
example)
curl https://api.fugaku.r-ccs.riken.jp/status -H "Authorization: Bearer $accessToken" -X GET
Status Codes:
Response JSON Object:

  • [].machine (string) – machine name (required)

  • [].status (string) – status (required)

GET /status/{machine}

get specified machine status

get specified machine status
Output the status of the specified machine.
example)
curl -ik https://api.fugaku.r-ccs.riken.jp/api/status/computer/ -H "Authorization: Bearer $accessToken" -X GET
Parameters:

  • machine (string) – machine name specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

Status Codes:
Response JSON Object:

  • machine (string) – machine name (required)

  • status (string) – status (required)

POST /file/{machine}/{file_path}

file upload

new file upload
Upload a file to the specified machine name and file path.
example)
curl https://api.fugaku.r-ccs.riken.jp/file/computer/home/hpcadmin/xxxxfile -H "Authorization: Bearer $accessToken" -X POST -d @xxxxfile
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

  • file_path (string) –

    upload file path
    Specify a file name.

Status Codes:
GET /file/{machine}/{file_path}

file download

file download
Download the file with the specified machine name and file path.
example)
curl https://api.fugaku.r-ccs.riken.jp/file/computer/home/hpcadmin/xxxxfile -H "Authorization: Bearer $accessToken"
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

  • file_path (string) –

    download file path
    specify a file name or folder.

Query Parameters:

  • view (string) –

    File information acquisition availability
    When read is not specified in the parameter, download the file specified in file_path.
    When read is specified in the parameter, output the file list of the specified directory.

Status Codes:

  • 200 OK –

    file download complete

    example

    When read is not specified: File data (binary format)

    When read is specified: {“status”: “OK”, “output”:-rw-rw-r– 1 f00156 f00156 119 2019-05-16 16:24 test.shn, “error”:””}

  • 400 Bad Request – parameter error

  • 403 Forbidden – authentication error

  • 500 Internal Server Error – internal server error

PUT /file/{machine}/{file_path}

file create/change

file upload/change
Upload (update) a file to the specified machine name and file path.
example)
curl https://api.fugaku.r-ccs.riken.jp/file/computer/home/hpcadmin/xxxxfile -H "Authorization: Bearer $accessToken" -X PUT -d @xxxxfile
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

  • file_path (string) –

    file path
    Specify a file name.

Status Codes:
GET /queue/{machine}

get list of executing jobs

get list of executing jobs API
On the target machine, get the list of executing jobs from the job scheduler.
When specify the job ID, get the list of sub job of job ID.
example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/ -H "Authorization: Bearer $accessToken" -X GET
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

Query Parameters:

  • index (integer) –

    index of first record
    When paging, specify it together with the limit.

  • limit (integer) –

    Maximum number of records
    If the number of records that meets the condition exceeds the limit, return from the old one sorted by the accept time of the job.

  • status (string) –

    job execution status
    Filter to jobs with the specified processing status.

  • jobid (string) –

    job ID
    specify the job ID, If you want to get a list of sub-jobs.

Status Codes:
Response JSON Object:

  • error (string) – error description (required)

  • output[].accept_time (string) – accept time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].bulkno (string) – bulk number

  • output[].cpu_num (integer) – used CPU number

  • output[].elapse (string) – elapsed time

  • output[].elapse_limit (string) – elapsed time limitation

  • output[].end_code (string) – end code

  • output[].end_time (string) – end time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].exit_subjob_num (string) – completed sub job number

  • output[].group (string) – user group name

  • output[].jid (string) – JID

  • output[].job_type (string) – job type

  • output[].jobid (string) – job ID (required)

  • output[].name (integer) – name (required)

  • output[].node_num (integer) – node shape/node number

  • output[].pjm_code (string) – PJM code

  • output[].queue (string) – queue (required)

  • output[].rsc_grp (string) – resource group name (required)

  • output[].start_time (string) – start time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].status (string) – job status ACC　:　Checking whether the job satisfies the acceptance conditions (items restricted with the job ACL function) RJT　:　Job acceptance rejected QUE　:　Waiting for a turn to execute the job, which has been accepted RNA　:　Reserving the resources required for job execution RNP　:　Executing the prologue process RUN　:　Executing the job RNE　:　Executing the epilogue process RNO　:　Job end processing is in progress EXT　:　Job end CCL　:　Job stopped by an instruction from the job submitter or the administrator HLD　:　Keeping the state of the submitted job from changing, when job execution has stopped ERR　:　Job stopped because of an error detected by the job operation management function (required)

  • output[].stepno (string) – step number

  • output[].subjob_depend (string) – sub job dependency judgment expression

  • output[].subjob_num (string) – sub job number

  • output[].subjobid (string) – sub job ID

  • output[].timeuse (string) – total cpu time (required)

  • output[].user (string) – username (required)

  • status (string) – status (required)

POST /queue/{machine}

job submission

job submission API
Execute a job submission command to the job scheduler from the specified machine.
For the parameter, specify either jobfile or jobscript.
(If both are specified, the jobfile parameter has priority)

parameter

operation examples

jobfile

/home/user01/test.sh<br>(specify file script)

jobscript

/home/user01/a.out < stdin.dat<br>(specify script command)

 
example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/ -H "Authorization: Bearer $accessToken" -X POST -d '{"jobfile": "/home/hpcadmin/aaa.sh", "qopt": "jid=100"}'
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

Status Codes:
Response JSON Object:

  • error (string) – error description (required)

  • output (string) – job ID (required)

  • status (string) – status (required)

GET /queue/{machine}/sacct

get completed job list

On the target machine, get a list of jobs completed within 24 hours from the job scheduler.
When specify the job ID, get the list of sub job of job ID.

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/sacct -H "Authorization: Bearer $accessToken"
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

Query Parameters:

  • index (integer) –

    index of first record
    When paging, specify it together with the limit.

  • limit (integer) –

    Maximum number of records
    If the number of records that meets the condition exceeds the limit, return from the old one sorted by the accept time of the job.

  • status (string) –

    job execution status
    Filter to jobs with the specified processing status.

  • jobid (string) –

    job ID
    specify the job ID, If you want to get a list of sub-jobs.

Status Codes:
Response JSON Object:

  • error (string) – error description (required)

  • output[].accept_time (string) – accept time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].bulkno (string) – bulk number

  • output[].cpu_num (integer) – used CPU number

  • output[].elapse (string) – elapsed time

  • output[].elapse_limit (string) – elapsed time limitation

  • output[].end_code (string) – end code

  • output[].end_time (string) – end time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].exit_subjob_num (string) – completed sub job number

  • output[].group (string) – user group name

  • output[].jid (string) – JID

  • output[].job_type (string) – job type

  • output[].jobid (string) – job ID (required)

  • output[].name (integer) – name (required)

  • output[].node_num (integer) – node shape/node number

  • output[].pjm_code (string) – PJM code

  • output[].queue (string) – queue (required)

  • output[].rsc_grp (string) – resource group name (required)

  • output[].start_time (string) – start time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].status (string) – job status ACC　:　Checking whether the job satisfies the acceptance conditions (items restricted with the job ACL function) RJT　:　Job acceptance rejected QUE　:　Waiting for a turn to execute the job, which has been accepted RNA　:　Reserving the resources required for job execution RNP　:　Executing the prologue process RUN　:　Executing the job RNE　:　Executing the epilogue process RNO　:　Job end processing is in progress EXT　:　Job end CCL　:　Job stopped by an instruction from the job submitter or the administrator HLD　:　Keeping the state of the submitted job from changing, when job execution has stopped ERR　:　Job stopped because of an error detected by the job operation management function (required)

  • output[].stepno (string) – step number

  • output[].subjob_depend (string) – sub job dependency judgment expression

  • output[].subjob_num (string) – sub job number

  • output[].subjobid (string) – sub job ID

  • output[].timeuse (string) – total cpu time (required)

  • output[].user (string) – username (required)

  • status (string) – status (required)

GET /queue/{machine}/{jobid}

get detailed job information

get detailed job information API
指定したジョブIDまたはサブジョブIDに該当するジョブの詳細情報を取得する。 

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/{jobid}  -H "Authorization: Bearer $accessToken" -X GET
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

  • jobid (string) –

    job ID
    specify the job ID for which you want to get detailed job information.

Status Codes:
Response JSON Object:

  • error (string) – error description (required)

  • output[].accept_time (string) – accept time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].bulkno (string) – bulk number

  • output[].cpu_num (integer) – used CPU number

  • output[].elapse (string) – elapsed time

  • output[].elapse_limit (string) – elapsed time limitation

  • output[].end_code (string) – end code

  • output[].end_time (string) – end time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].exit_subjob_num (string) – completed sub job number

  • output[].group (string) – user group name

  • output[].jid (string) – JID

  • output[].job_type (string) – job type

  • output[].jobid (string) – job ID (required)

  • output[].name (integer) – name (required)

  • output[].node_num (integer) – node shape/node number

  • output[].pjm_code (string) – PJM code

  • output[].queue (string) – queue (required)

  • output[].rsc_grp (string) – resource group name (required)

  • output[].start_time (string) – start time（yyyy-MM-ddTHH:mm:ss+09:00）

  • output[].status (string) – job status ACC　:　Checking whether the job satisfies the acceptance conditions (items restricted with the job ACL function) RJT　:　Job acceptance rejected QUE　:　Waiting for a turn to execute the job, which has been accepted RNA　:　Reserving the resources required for job execution RNP　:　Executing the prologue process RUN　:　Executing the job RNE　:　Executing the epilogue process RNO　:　Job end processing is in progress EXT　:　Job end CCL　:　Job stopped by an instruction from the job submitter or the administrator HLD　:　Keeping the state of the submitted job from changing, when job execution has stopped ERR　:　Job stopped because of an error detected by the job operation management function (required)

  • output[].stepno (string) – step number

  • output[].subjob_depend (string) – sub job dependency judgment expression

  • output[].subjob_num (string) – sub job number

  • output[].subjobid (string) – sub job ID

  • output[].timeuse (string) – total cpu time (required)

  • output[].user (string) – username (required)

  • status (string) – status (required)

DELETE /queue/{machine}/{jobid}

job cancel

cancel the job corresponding to the specified job ID.
By using “- (hyphen)”, the range of job ID can be specified. You can specify the range of the sub job ID as well.

Example: When specifying a range of job ID 1 to 100

1-100

Example: When specifying the range of step numbers 1 to 10 of the step job (job ID=100)

100_1-10

Example: When specifying the range of bulk numbers 1 to 10 of the bulk job (job ID=101)

101[1-10]

When range is specified, an error will not occur even if the following jobs are included in the range, the job will be ignored, and processing will continue.

Job that do not exist, job that the user does not have permission, job that cannot be specified

If successful, returns all job IDs specified, with or without cancel ignoring.

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/{jobid}  -H "Authorization: Bearer $accessToken"  -X delete
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

  • jobid (string) –

    job ID
    Specifies the job ID of the job to be deleted.

Status Codes:
Response JSON Object:

  • error (string) – error description (required)

  • output (string) – job cancellation output result (jobid) (required)

  • status (string) – status (required)

PUT /queue/{machine}/jobscript

job execution script generate/change

job execution script generate/change API
Create the job execution script on the target machine. If a file with the same name exists, it will be overwritten.
When creating the bulk job or step job, specify JTYPE of COMMON_DATA.

example)
curl https://api.fugaku.r-ccs.riken.jp/queue/computer/jobscript -H "Authorization: Bearer $accessToken" -X PUT -d '{"script":{"APP_DATA":{"ProgramGroupList":{"ProgramGroup":[{"ProgramList":{"Program":[{"Type":"mpi","FileName":"a.sh","ThreadMode":"parallel","Threads":"100"}]},"GroupType":"serialgroup"}]}},"COMMON_DATA":{}}}'
Parameters:

  • machine (string) –

    machine name
    specify the machine name obtained by getting the status of all machines (/status/).Normally, specify “computer”.

Request JSON Object:

  • filename (string) –

  • script.APP_DATA.ProgramGroupList.ProgramGroup.GroupType (string) –

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Argument (string) – Execution program arguments

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].Collect (integer) – When not distinguishing files staged out from each rank: 1 When not specified, the rank number is added to the end of the staged out file name.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].FileName (string) – File input/output by the execution program.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].IsDirectory (integer) – When file staging the directory: 1

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].Rank (string) – Specify the rank number for staging.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].StageIn (integer) – When staging in the file: 1

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].StageOut (integer) – When staging out the file: 1

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileInfoList[].UnitNo (string) – Specify the device number corresponding to the file input/output by the executing program. Enabled only when the execution program is Fortran.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.FileName (string) – execution program name (required)

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Procs (string) – thread number per process. Enabled only when the execution program is thread parallel.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdInFileName (string) – standard input file name

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdInRank (string) – rank number of the file staging node for the standard input file.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdOutCollect (integer) – *When not distinguishing files staged out from each rank：1 *When not specified, the rank number is added to the end of the staged out file name.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdOutFileName (string) – standard output file name

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.StdOutRank (string) – rank number of the file staging node for the standard output file.

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.ThreadMode (string) – ・For automatic parallel：”parallel” ・For OpenMP:：”omp” ・For 1 thread process：not specified

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Threads (integer) – program execution thread number

  • script.APP_DATA.ProgramGroupList.ProgramGroup.ProgramList.Program.Type (string) – ・ When executing as a standalone program：”serial” ・When executing as a MPI parallel program：”mpi”

  • script.COMMON_DATA.DEPEND_JID (string) – Dependent job ID specification. Enabled only when “S” is specified for the job type identifier.

  • script.COMMON_DATA.ELAPSE (string) – Maximum job execution time setting. The following 3 patterns can be

  • script.COMMON_DATA.JGRP (string) – Job accounting group specification.

  • script.COMMON_DATA.JNAME (string) – name Up to 63 single-byte alphanumeric characters can be specified. The first character is only half-width alphabetic characters. There are four types of symbols, “-_@.”.

  • script.COMMON_DATA.JTYPE (string) – job type identifier For normal job: not specified For bulk job: “B” For step job: “S”

  • script.COMMON_DATA.NODE (string) – Specify the node shape assigned to the job. Specify in one of X, XxY, XxYxZ format.

  • script.COMMON_DATA.NODES (integer) – The number of MPI processes to start statically, when the executing program is an MPI parallel program.

  • script.COMMON_DATA.QOPT (string) – Queue option specification.

  • script.COMMON_DATA.QUEUE (string) – Specify the group name of the resource that submits the job.

  • script.COMMON_DATA.QUOTA (string) – Maximum value (in GB) of disk usage used by the job.

  • script.COMMON_DATA.QUOTA_TYPE (string) – Quota type specification.

  • script.COMMON_DATA.SNUM (string) – Own sub job number Enabled only when “S” is specified for the job type identifier.

  • script.COMMON_DATA.STEP_CODE (string) – Dependent sub job ID Enabled only when “S” is specified for the job type identifier.

  • script.COMMON_DATA.STEP_CONDITION (string) – Dependency equation Enabled only when “S” is specified for the job type identifier.

  • script.COMMON_DATA.SUBJOBS_NODE (integer) – Bulk job node number Enabled only when “B” is specified for the job type identifier.

  • script.COMMON_DATA.SUBJOB_END (string) – Bulk job end number. Enabled only when “B” is specified for the job type identifier.

  • script.COMMON_DATA.SUBJOB_START (string) – Bulk job start number. Enabled only when “B” is specified for the job type identifier.

  • script.COMMON_DATA.SYSTEM (string) – Specify the unit name of the resource that submits the job.

  • script.COMMON_DATA.USE_RANK_DIR (string) – Specification existence flag of user rank directory.

  • script.COMMON_DATA.USE_RANL_DIR (boolean) – When using the rank number directory: true

Status Codes:
Response JSON Object:

  • error (string) – error description (required)

  • output (string) – job execution script generation result (required)

  • status (string) – status (required)