Newer
Older
API Documentation
====================================================================================================================
Implements API for IT4I SCS Information System.
There 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: `6ecb1bb3 / 2022-05-10 13:51:59 +0200`
- apidoc building date: `2022-05-10 11:55:40 +0000`
Summary
-------------------------------------------------------------------------------------
<table>
<colgroup>
<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>
<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>
<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>
<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>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>
<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>
<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>
<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>
<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>
- **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>
- **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
- **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
- <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>
- **login** (*string*) – account id
- **it4ifreetoken** (*string*) – token
- **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
- <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
[
{
"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 CPU core for 1 hour, it
consumes 1 core-hour from the project’s resources. However, some
calculations (or their placement) can be cheaper. Actual consumed
core-hours are reduced by a cheapening factor and then deducted from the
<a href="https://docs.it4i.cz/general/resources-allocation-policy/#normalized-core-hours-nch" class="reference external">link</a>
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)
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4ifree" class="reference external">it4ifree</a>
- **login** (*string*) – account id
- **it4ifreetoken** (*string*) – token
- **login** (*string*) – account id
- **pi\_login** (*string*) – PI account id
- **pid** (*string*) – project id
- **type** (*string*) – project type, S for standard, M-1, M-2, M-3,
M-4 for multiyear project in particular period
- **days\_left** (*string*) – days to the end of project, or inactive,
expired, forthcoming, upcoming, unlimited
- **free** (*int*) – free core-hours which can still be 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
- <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": [
{
"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,
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
"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",
"type": "S"
},
{
"core_hours": 0,
"core_hours_with_factor": 0,
"login": "johnsm",
"pi_login": "johnsm",
"pid":"DD-13-6",
"type": "S"
},
{
"core_hours": 0,
"core_hours_with_factor": 0,
"login": "johnsm",
"pi_login": "johnsm",
"pid":"DD-1-1",
"type": "M-1"
}
]
}
<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>
- **notice** – returns only notice messages
- **important** – returns only important messages
- **all** – returns all messages
- **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
- **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
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
- <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.
- **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"
}
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
<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’
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
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.
- **hostname** (*string*) – system hostname
- **revision** (*string*) – API revision / build time
- **version** (*string*) – API version
- <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"
}