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: `d110fd35 / 2020-06-08 07:33:47 +0200`
- apidoc building date: `2020-06-08 12:58:10 +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>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
- **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"}' \
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
- **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
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
- **cluster** (*string*) – cluster id or ‘all’
- **cluster** (*string*) – cluster id or ‘all’
- **fs** (*string*) – filesystem name
- **hard\_quota\_files** (*int*) – file number quota
- **hard\_quota\_space** (*int*) – space quota (in Kb)
- **ldapuser** (*string*) – user id
- **updated\_at** (*string*) – date of last update
- **usage\_files** (*int*) – number of files on filesystem
- **usage\_space** (*int*) – amount of space used
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
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/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="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>
Request JSON Object
- **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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
- **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,
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
"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>
Query Parameters
- **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
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
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.
- **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="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
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"
}