API Documentation

Implements API for IT4I SCS Information System.

  • api revision: 22b30077 / 2018-01-16 10:03:52 +0100
  • api version: 0.9-31-g22b3007
  • apidoc building date: 2018-01-16 09:05:14 +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
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
version GET /api/v1/version API version

API Details

POST /api/v1/check-access

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

Request JSON Object:

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

Status Codes:

Example request:

curl -i -H "Content-Type:application/json" -X POST \
  --data '{"pid":"DD-13-5","login":"johnsm","queue":"qfat"}' \
  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/(cluster_type)

Returns list of times dedicated for HPC maintainance. It is not possible to use HPC services during maintainance.

Query Parameters:

  • all – returns all dedicated times for all clusters
  • salomon – returns all times just for salomon cluster
  • anselm – returns all times just for anselm 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

Status Codes:

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/it4ifree/(login)

A service to check resources of the projects on which the account participate. If the calculation run on 1 cpu core during 1 hour, it consumes 1 core-hour from the project resources. However, some calculations (or their placement) can be cheaper. Actual consumed core-hours are reduced by a cheaping factor and then deduct from the project resources. See link for more details about so-called normalized core-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)

    Request JSON Object:

  • login (string) – account id

  • it4ifreetoken (string) – token

Response JSON Object:

  • login (string) – account id
  • pid (string) – project id
  • pi_login (string) – account id which is PI
  • days_left (string) – days to the end of project, --- if project is inactive or not yet started
  • free (int) – free core-hours which can be still consumed
  • total (int) – total core-hours assigned to the project
  • used (int) – actual consumed core-hours
  • used_with_factor (int) – consumed normalized core-hours
  • used_by_me (int) – core-hours consumed by the account
  • used_by_me_with_factor (int) – normalized core-hours consumed by the account
  • corehours (int) – core-hours consumed by the account
  • core_hours_with_factor (int) – normalized core-hours consumed by the account

Status Codes:

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": [
    {
      "days_left": "---",
      "free": 17124,
      "login": "johnsm",
      "pid": "DD-13-6",
      "total": 100000,
      "used": 82876,
      "used_by_me": 0,
      "used_by_me_with_factor": 0,
      "used_with_factor":82876
    },
    {
      "days_left": "---",
      "free": 0,
      "login": "johnsm",
      "pid": "DD-14-12",
      "total": 1000,
      "used": 8641,
      "used_by_me": 0,
      "used_by_me_with_factor": 0,
      "used_with_factor": 8641
    }
  ],
  "me_as_pi": [
    {
      "core_hours": 82876,
      "core_hours_with_factor": 82876,
      "login":"abc",
      "pi_login": "johnsm",
      "pid": "DD-13-6"
    },
    {
      "core_hours": 0,
      "core_hours_with_factor": 0,
      "login": "johnsm",
      "pi_login": "johnsm",
      "pid":"DD-13-6"
    }
  ]
}

GET /api/v1/motd/(category)

Returns SCS messages of the day.

Query Parameters:

  • notice – returns only notice messages
  • important – returns only important messages
  • all – returns all messages

Status Codes:

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:

Example request:

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

Example response:

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

{
   "message": "pong"
}

GET /api/v1/version

Returns basic information about API.

Response JSON Object:

  • hostname (string) – system hostname
  • revision (string) – api revision / build time
  • version (string) – api version

Status Codes:

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"
}