scs_api.server_public.md

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
<a href="https://pypi.org/project/it4i.portal.clients" class="uri reference external">https://pypi.org/project/it4i.portal.clients</a>

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: `90ab4272 / 2023-07-28 13:01:56 +0200`

- api version: `1.0-81-g90ab427`

- apidoc building date: `2023-07-28 11:04:24 +0000`

Summary
-------------------------------------------------------------------------------------

<table>
<colgroup>
<col style="width: 20%" />
<col style="width: 45%" />
<col style="width: 35%" />
</colgroup>
<thead>
<tr class="header">
<th><p>Resource</p></th>
<th><p>Operation</p></th>
<th><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>check-access</p></td>
<td><p><a href="#post--api-v1-check-access" class="reference external">POST /api/v1/check-access</a></p></td>
<td><p>Access check to queue</p></td>
</tr>
<tr class="even">
<td><p>dedicated-time</p></td>
<td><p><a href="#get--api-v1-dedicated-time-(cluster_type)" class="reference external">GET /api/v1/dedicated-time/(cluster_type)</a></p></td>
<td><p>HPC dedicated time</p></td>
</tr>
<tr class="odd">
<td><p>dedicated-time-calendar</p></td>
<td><p><a href="#get--api-v1-dedicated-time-calendar" class="reference external">GET /api/v1/dedicated-time-calendar</a></p></td>
<td><p>Dedicated time calendar</p></td>
</tr>
<tr class="even">
<td><p>fs-usage</p></td>
<td><p><a href="#post--api-v1-fs-usage" class="reference external">POST /api/v1/fs-usage</a></p></td>
<td><p>Shows filesystem usage</p></td>
</tr>
<tr class="odd">
<td><p>it4ifree</p></td>
<td><p><a href="#post--api-v1-it4ifree-(login)" class="reference external">POST /api/v1/it4ifree/(login)</a></p></td>
<td><p>Free account resources</p></td>
</tr>
<tr class="even">
<td><p>motd</p></td>
<td><p><a href="#get--api-v1-motd-(category)" class="reference external">GET /api/v1/motd/(category)</a></p></td>
<td><p>SCS messages of the day</p></td>
</tr>
<tr class="odd">
<td><p>ping</p></td>
<td><p><a href="#get--api-v1-ping" class="reference external">GET /api/v1/ping</a></p></td>
<td><p>Connection test</p></td>
</tr>
<tr class="even">
<td><p>project-fs-usage</p></td>
<td><p><a href="#post--api-v1-project-fs-usage" class="reference external">POST /api/v1/project-fs-usage</a></p></td>
<td><p>Shows project filesystem usage</p></td>
</tr>
<tr class="odd">
<td><p>user-fs-usage</p></td>
<td><p><a href="#post--api-v1-user-fs-usage" class="reference external">POST /api/v1/user-fs-usage</a></p></td>
<td><p>Shows user filesystem usage</p></td>
</tr>
<tr class="even">
<td><p>version</p></td>
<td><p><a href="#get--api-v1-version" class="reference external">GET /api/v1/version</a></p></td>
<td><p>API version</p></td>
</tr>
</tbody>
</table>

API Details
---------------------------------------------------------------------------------------------

<a name="post--api-v1-check-access" class="headerlink" title="Permalink to this definition"></a>
 **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
<a href="https://pypi.org/project/it4i.portal.clients/#it4icheckaccess" class="reference external">it4icheckaccess</a>

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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – 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."

<a name="get--api-v1-dedicated-time-calendar" class="headerlink" title="Permalink to this definition"></a>
 **GET /api/v1/dedicated-time-calendar**

A service with a public dedicated time calendar.

<a name="get--api-v1-dedicated-time-(cluster_type)" class="headerlink" title="Permalink to this definition"></a>
 **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
<a href="https://pypi.org/project/it4i.portal.clients/#it4idedicatedtime" class="reference external">it4idedicatedtime</a>

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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – no error

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6" class="reference external">405 Method Not Allowed</a>
    – 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"
      }
    ]

<a name="post--api-v1-fs-usage" class="headerlink" title="Permalink to this definition"></a>
 **POST /api/v1/fs-usage**

A service to show filesystem usage.

Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4ifsusage" class="reference external">it4ifsusage</a>

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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – no error

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6" class="reference external">405 Method Not Allowed</a>
    – 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
        }
      ]

<a name="post--api-v1-it4ifree-(login)" class="headerlink" title="Permalink to this definition"></a>
 **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
<a href="https://docs.it4i.cz/general/resources-allocation-policy/" class="reference external">link</a>
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
<a href="https://pypi.org/project/it4i.portal.clients/#it4ifree" class="reference external">it4ifree</a>

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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – no error

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6" class="reference external">405 Method Not Allowed</a>
    – 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
        },
      ]
    }

<a name="get--api-v1-motd-(category)" class="headerlink" title="Permalink to this definition"></a>
 **GET /api/v1/motd/**(category)

Returns SCS messages of the day.

Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4imotd" class="reference external">it4imotd</a>

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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – no error

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6" class="reference external">405 Method Not Allowed</a>
    – 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"
      }
    ]

<a name="get--api-v1-ping" class="headerlink" title="Permalink to this definition"></a>
 **GET /api/v1/ping**

A service for testing connection to API.

Response JSON Object

- **message** (*string*) – reply message ‘pong’

Status Codes

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – 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"
    }

<a name="post--api-v1-project-fs-usage" class="headerlink" title="Permalink to this definition"></a>
 **POST /api/v1/project-fs-usage**

A service to show project filesystem usage.

Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4iprojectfsusage" class="reference external">it4iprojectfsusage</a>

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

<a name="post--api-v1-user-fs-usage" class="headerlink" title="Permalink to this definition"></a>
 **POST /api/v1/user-fs-usage**

A service to show user filesystem usage.

Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4iuserfsusage" class="reference external">it4iuserfsusage</a>

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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – no error

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6" class="reference external">405 Method Not Allowed</a>
    – 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
        }
      ]

<a name="get--api-v1-version" class="headerlink" title="Permalink to this definition"></a>
 **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

- <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1" class="reference external">200 OK</a>
    – 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"
    }