API Documentation

Implements API for IT4I SCS Information System.

This is a PyPI package, which provides a simple user-friendly shell interface to call API requests and display their response. The package is available on https://pypi.org/project/it4i.portal.clients

The number of requests you may make to IT4I API is limited. The rate limit can be changed without prior notice at any time, but the default is 6 requests per minute. Exceeding the limit will lead to your IP address being temporarily blocked from making further requests. The block will automatically be lifted by waiting an hour.

• api revision: 61af7c9d / 2024-01-08 18:14:05 +0100

• api version: 1.0-82-g61af7c9

• apidoc building date: 2024-01-09 09:29:20 +0000

Summary

Resource	Operation	Description
check-access	POST /api/v1/check-access	Access check to queue
dedicated-time	GET /api/v1/dedicated-time/(cluster_type)	HPC dedicated time
dedicated-time-calendar	GET /api/v1/dedicated-time-calendar	Dedicated time calendar
fs-usage	POST /api/v1/fs-usage	Shows filesystem usage
it4ifree	POST /api/v1/it4ifree/(login)	Free account resources
motd	GET /api/v1/motd/(category)	SCS messages of the day
ping	GET /api/v1/ping	Connection test
project-fs-usage	POST /api/v1/project-fs-usage	Shows project filesystem usage
user-fs-usage	POST /api/v1/user-fs-usage	Shows user filesystem usage
version	GET /api/v1/version	API version

API Details

POST /api/v1/check-access

A service to check if an account and/or related project has an access to a specified queue.

Terminal implementation is available at it4icheckaccess

Request JSON Object

• login (string) – account id

• queue (string) – queue id

• cluster (string) – cluster name

• pid (string) – project id, not required if querying a projectless queue

Status Codes

• 200 OK – no error

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"pid":"DD-13-5","login":"johnsm","queue":"qfat","cluster":"barbora"}' \
  https://scs.it4i.cz/api/v1/check-access

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

"OK Access granted for regular queue."

GET /api/v1/dedicated-time-calendar

A service with a public dedicated time calendar.

GET /api/v1/dedicated-time/(cluster_type)

Returns a list of times dedicated for HPC maintenance. During maintenance, HPC services are not available.

Terminal implementation is available at it4idedicatedtime

Query Parameters

• all – returns all dedicated times for all clusters

• salomon – returns all times just for the Salomon cluster

• anselm – returns all times just for the Anselm cluster

• karolina – returns all times just for the Karolina cluster

• barbora – returns all times just for the Barbora cluster

• dgx – returns all times just for the DGX-2 cluster

• active – returns dedicated times for all clusters which are now active

• planned – returns dedicated times for all clusters which are now active or scheduled in the future

Response JSON Object

• cluster_type (string) – cluster id

• dateEfficiency (string) – maintenance start date

• dateExpiration (string) – maintenance end date

• updated_at (string) – date of the list’s last update

Status Codes

• 200 OK – no error

• 405 Method Not Allowed – invalid requested query parameter

Example request:

curl -i https://scs.it4i.cz/api/v1/dedicated-time/all

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "cluster_type": "salomon",
    "dateEfficiency": "2017-11-21 09:45:00",
    "dateExpiration": "2017-11-21 23:59:00",
    "updated_at": "2017-11-21 09:45:00"
  }
]

POST /api/v1/fs-usage

A service to show filesystem usage.

Terminal implementation is available at it4ifsusage

Request JSON Object

• login (string) – account id

• it4ifreetoken (string) – token

Response JSON Object

• type (string) – type of quota

• cluster_or_pid (string) – cluster name of project identifier

• fs (string) – filesystem name

• usage_space (int) – amount of space used (in KB)

• usage_files (int) – number of files on filesystem

• hard_quota_space (int) – space quota (in KB)

• hard_quota_files (int) – file number quota

• updated_at (string) – date of last update

Status Codes

• 200 OK – no error

• 405 Method Not Allowed – invalid requested query parameter

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"login":"johnsm", "it4ifreetoken": "abc"}' \
  https://scs.it4i.cz/api/v1/fs-usage

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  [
    {
      "login": "johnsm",
      "type": "User",
      "cluster_or_pid": "salomon"
      "fs": "/home",
      "hard_quota_files": 500000,
      "hard_quota_space": 250000000,
      "updated_at": "2019-03-11 13:25:16",
      "usage_files": 19,
      "usage_space": 2620
    }
  ]

POST /api/v1/it4ifree/(login)

A service to check resources of the projects on which the account participates. If the calculation runs on 1 node core for 1 hour, it consumes 1 node-hour from the project’s resources. See link for more details about so-called node-hours. The JSON response contains two parts:

• me – data from projects, where the account has access

• me_as_pi – data from projects, where the account is PI (primary investigator)

  Terminal implementation is available at it4ifree

Request JSON Object

• login (string) – account id

• it4ifreetoken (string) – token

Response JSON Object

• login (string) – account id

• pi_login (string) – PI account id

• pid (string) – project id

• type (string) – project resource type, eg.: Karolina CPU, Barbora GPU, DGX-2,… project in particular period

• days_left (string) – days to the end of project, or inactive, expired, forthcoming, upcoming, unlimited

• free (int) – free node-hours which can still be consumed

• total (int) – total node-hours assigned to the project

• used (int) – actual consumed node-hours

• used_by_me (int) – node-hours consumed by the account

• nodehours (int) – core-hours consumed by the account

Status Codes

• 200 OK – no error

• 405 Method Not Allowed – token does not match

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"login":"johnsm", "it4ifreetoken": "abc"}' \
  https://scs.it4i.cz/api/v1/it4ifree/johnsm

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "me": [
    {
    "by_me":0.0,
    "days_left":"244",
    "free":7434148.1,
    "pid":"DD-13-6",
    "resource_type":"Legacy Normalized Core Hours",
    "total":7470000.0,
    "used":35851.9
    },
    {
    "by_me":32.4,
    "days_left":"220",
    "free":67.6,
    "pid":"DD-1-1",
    "resource_type":"Barbora CPU",
    "total":100.0,
    "used":32.4
    },

  ],
  "me_as_pi": [
    {"login":"johnsm",
    "pid":"DD-13-6",
    "resource_type":"Legacy Normalized Core Hours",
    "total":7470000.0,
    "usage":35851.9
    },
    {"login":"johnsm",
    "pid":"DD-1-1",
    "resource_type":"Barbora CPU",
    "total":100.0,
    "usage":32.4
    },
  ]
}

GET /api/v1/motd/(category)

Returns SCS messages of the day.

Terminal implementation is available at it4imotd

Query Parameters

• notice – returns only notice messages

• important – returns only important messages

• all – returns all messages

Response JSON Object

• author (string) – author of the message

• category (string) – message category

• created_at (string) – creation date

• dateEfficiency (string) – effective date

• dateExpiration (string) – expiration date

• dateModification (string) – date the message was modified

• deleted_at (string) – date the message was deleted

• id (int) – message id

• messageBody (string) – the text of the message

• state (string) – obsolete, no longer used

• title (string) – the title of the message

• typeMotd (string) – obsolete, no longer used

• updated_at (string) – date of the list’s last update

Status Codes

• 200 OK – no error

• 405 Method Not Allowed – invalid requested query parameter

Example request:

curl -i https://scs.it4i.cz/api/v1/motd/notice

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "author": "svi47",
    "category": "notice",
    "created_at": "2017-10-12 11:44:51",
    "dateEfficiency": "2017-10-12 11:41:00",
    "dateExpiration": "2017-11-28 14:30:00",
    "dateModification": "2017-10-12 13:44:51",
    "deleted_at": null,
    "id": 169,
    "messageBody": "For more information about the course,
      please visit its web page: https://goo.gl/cvFsFH",
    "state": null,
    "title": "Invitation to the Course Productivity Tools
      for High Performance Computing (2017-11-27 to 2017-11-28)",
    "typeMotd": null,
    "updated_at": "2017-10-12 11:44:51"
  }
]

GET /api/v1/ping

A service for testing connection to API.

Response JSON Object

• message (string) – reply message ‘pong’

Status Codes

• 200 OK – no error

Example request:

curl -i https://scs.it4i.cz/api/v1/ping

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "message": "pong"
}

POST /api/v1/project-fs-usage

A service to show project filesystem usage.

Terminal implementation is available at it4iprojectfsusage

Request JSON Object

• login (string) – account id

• it4ifreetoken (string) – token

• pid (string) – project identifier or all

Response JSON Object

• pid (string) – project identifier

• fs (string) – filesystem name

• usage_space (int) – amount of space used (in KB)

• usage_files (int) – number of files on filesystem

• hard_quota_space (int) – space quota (in KB)

• hard_quota_files (int) – file number quota

• updated_at (string) – date of last update

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"login":"johnsm", "it4ifreetoken": "abc","pid":"all"}' \
  https://scs.it4i.cz/api/v1/project-fs-usage

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  [
    {
      "pid": "dd-13-5",
      "fs": "/home",
      "hard_quota_files": 500000,
      "hard_quota_space": 250000000,
      "login": "johnsm",
      "updated_at": "2019-03-11 13:25:16",
      "usage_files": 19,
      "usage_space": 2620
    }
  ]

POST /api/v1/user-fs-usage

A service to show user filesystem usage.

Terminal implementation is available at it4iuserfsusage

Request JSON Object

• login (string) – account id

• it4ifreetoken (string) – token

• cluster (string) – cluster name or ‘all’

Response JSON Object

• cluster (string) – cluster name

• fs (string) – filesystem name

• usage_space (int) – amount of space used (in KB)

• usage_files (int) – number of files on filesystem

• hard_quota_space (int) – space quota (in KB)

• hard_quota_files (int) – file number quota

• updated_at (string) – date of last update

Status Codes

• 200 OK – no error

• 405 Method Not Allowed – invalid requested query parameter

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"login":"johnsm", "it4ifreetoken": "abc","cluster":"all"}' \
  https://scs.it4i.cz/api/v1/user-fs-usage

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

  [
    {
      "cluster": "anselm",
      "fs": "/home",
      "hard_quota_files": 500000,
      "hard_quota_space": 250000000,
      "ldapuser": "johnsm",
      "updated_at": "2019-03-11 13:25:16",
      "usage_files": 19,
      "usage_space": 2620
    }
  ]

GET /api/v1/version

Returns basic information about the API.

Response JSON Object

• hostname (string) – system hostname

• revision (string) – API revision / build time

• version (string) – API version

Status Codes

• 200 OK – no error

Example request:

curl -i https://scs.it4i.cz/api/v1/version

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "hostname": "scs.it4i.cz",
   "revision": "ceac8aa / 2017-11-01 12:25:27 +0100",
   "version": "0.8.2-34-gceac8aa"
}