scs_api.server_public.md 18 KB
Newer Older
1

scs-ror's avatar
scs-ror committed
2
API Documentation
3
=====================================================================================================
scs-ror's avatar
scs-ror committed
4
5
6

Implements API for IT4I SCS Information System.

7
This is a PyPI package, which provides a simple user-friendly shell
8
9
interface to call API requests and display their response. The package
is available on
10
<a href="https://pypi.org/project/it4i.portal.clients" class="uri reference external">https://pypi.org/project/it4i.portal.clients</a>
scs-ror's avatar
scs-ror committed
11

12
13
14
15
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
scs-ror's avatar
scs-ror committed
16
17
block will automatically be lifted by waiting an hour.

18
- api revision: `44e95a30 / 2022-07-15 13:20:18 +0000`
19

20
- api version: `1.0-46-g44e95a3`
21

22
- apidoc building date: `2022-07-15 13:21:43 +0000`
scs-ror's avatar
scs-ror committed
23
24
25
26
27
28

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

<table>
<colgroup>
29
<col style="width: 20%" />
30
31
<col style="width: 45%" />
<col style="width: 35%" />
scs-ror's avatar
scs-ror committed
32
33
34
</colgroup>
<thead>
<tr class="header">
35
36
37
<th><p>Resource</p></th>
<th><p>Operation</p></th>
<th><p>Description</p></th>
scs-ror's avatar
scs-ror committed
38
39
40
41
</tr>
</thead>
<tbody>
<tr class="odd">
42
43
44
<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>
scs-ror's avatar
scs-ror committed
45
46
</tr>
<tr class="even">
47
48
49
<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>
scs-ror's avatar
scs-ror committed
50
51
</tr>
<tr class="odd">
52
53
<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>
54
<td><p>Dedicated time calendar</p></td>
scs-ror's avatar
scs-ror committed
55
56
</tr>
<tr class="even">
57
58
<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>
59
<td><p>Shows filesystem usage</p></td>
scs-ror's avatar
scs-ror committed
60
61
</tr>
<tr class="odd">
62
63
64
<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>
scs-ror's avatar
scs-ror committed
65
66
</tr>
<tr class="even">
67
68
69
<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>
scs-ror's avatar
scs-ror committed
70
71
</tr>
<tr class="odd">
72
73
74
<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>
scs-ror's avatar
scs-ror committed
75
76
</tr>
<tr class="even">
77
78
79
80
81
<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">
82
83
84
85
<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>
86
<tr class="even">
87
88
89
<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>
scs-ror's avatar
scs-ror committed
90
91
92
93
94
95
96
97
98
99
</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**

100
101
A service to check if an account and/or related project has an access to
a specified queue.
scs-ror's avatar
scs-ror committed
102

scs-ror's avatar
scs-ror committed
103
104
105
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4icheckaccess" class="reference external">it4icheckaccess</a>

106
Request JSON Object
107

108
109
110
111
- **login** (*string*) – account id

- **queue** (*string*) – queue id

112
113
- **cluster** (*string*) – cluster name

114
- **pid** (*string*) – project id, not required if querying a
115
116
117
    projectless queue

Status Codes
118

119
120
121
122
123
124
- <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 \
125
      --data '{"pid":"DD-13-5","login":"johnsm","queue":"qfat","cluster":"barbora"}' \
126
127
128
129
130
131
132
      https://scs.it4i.cz/api/v1/check-access

**Example response**:

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

133
    "OK Access granted for regular queue."
scs-ror's avatar
scs-ror committed
134
135
136
137

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

138
A service with a public dedicated time calendar.
scs-ror's avatar
scs-ror committed
139
140
141
142

<a name="get--api-v1-dedicated-time-(cluster_type)" class="headerlink" title="Permalink to this definition"></a>
 **GET /api/v1/dedicated-time/**(cluster\_type)

143
144
Returns a list of times dedicated for HPC maintenance. During
maintenance, HPC services are not available.
scs-ror's avatar
scs-ror committed
145

scs-ror's avatar
scs-ror committed
146
147
148
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4idedicatedtime" class="reference external">it4idedicatedtime</a>

149
Query Parameters
150

151
152
- **all** – returns all dedicated times for all clusters

153
- **salomon** – returns all times just for the Salomon cluster
154

155
- **anselm** – returns all times just for the Anselm cluster
156

157
158
- **karolina** – returns all times just for the Karolina cluster

159
- **barbora** – returns all times just for the Barbora cluster
160

161
- **dgx** – returns all times just for the DGX-2 cluster
162
163
164
165
166
167

- **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
168

169
Response JSON Object
170

171
172
173
174
175
176
- **cluster\_type** (*string*) – cluster id

- **dateEfficiency** (*string*) – maintenance start date

- **dateExpiration** (*string*) – maintenance end date

177
- **updated\_at** (*string*) – date of the list’s last update
178

179
Status Codes
180

181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
- <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"
      }
    ]
scs-ror's avatar
scs-ror committed
204
205
206
207
208
209

<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.

210
211
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4ifsusage" class="reference external">it4ifsusage</a>
scs-ror's avatar
scs-ror committed
212

213
Request JSON Object
214

215
216
217
218
- **login** (*string*) – account id

- **it4ifreetoken** (*string*) – token

219
Response JSON Object
220

221
222
223
- **type** (*string*) – type of quota

- **cluster\_or\_pid** (*string*) – cluster name of project identifier
224
225
226

- **fs** (*string*) – filesystem name

227
- **usage\_space** (*int*) – amount of space used (in KB)
228

229
- **usage\_files** (*int*) – number of files on filesystem
230

231
- **hard\_quota\_space** (*int*) – space quota (in KB)
232

233
- **hard\_quota\_files** (*int*) – file number quota
234

235
- **updated\_at** (*string*) – date of last update
236

237
Status Codes
238

239
240
241
242
243
244
245
246
247
- <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 \
248
      --data '{"login":"johnsm", "it4ifreetoken": "abc"}' \
249
250
251
252
253
254
255
256
257
      https://scs.it4i.cz/api/v1/fs-usage

**Example response**:

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

      [
        {
258
          "login": "johnsm",
259
          "type": "User",
260
          "cluster_or_pid": "salomon"
261
262
263
264
265
266
267
268
          "fs": "/home",
          "hard_quota_files": 500000,
          "hard_quota_space": 250000000,
          "updated_at": "2019-03-11 13:25:16",
          "usage_files": 19,
          "usage_space": 2620
        }
      ]
scs-ror's avatar
scs-ror committed
269
270
271
272
273

<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
274
275
276
277
278
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:
scs-ror's avatar
scs-ror committed
279
280

- `me` – data from projects, where the account has access
281
>
scs-ror's avatar
scs-ror committed
282
283
- `me_as_pi` – data from projects, where the account is PI (primary
    investigator)
284
>
scs-ror's avatar
scs-ror committed
285
286
287
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4ifree" class="reference external">it4ifree</a>

288
Request JSON Object
289

290
291
292
- **login** (*string*) – account id

- **it4ifreetoken** (*string*) – token
293

294
Response JSON Object
295

296
297
298
299
300
301
- **login** (*string*) – account id

- **pi\_login** (*string*) – PI account id

- **pid** (*string*) – project id

302
303
- **type** (*string*) – project resource type, eg.: Karolina CPU,
    Barbora GPU, DGX-2,… project in particular period
304
305
306
307

- **days\_left** (*string*) – days to the end of project, or inactive,
    expired, forthcoming, upcoming, unlimited

308
- **free** (*int*) – free node-hours which can still be consumed
309

310
- **total** (*int*) – total node-hours assigned to the project
311

312
- **used** (*int*) – actual consumed node-hours
313

314
- **used\_by\_me** (*int*) – node-hours consumed by the account
315

316
- **nodehours** (*int*) – core-hours consumed by the account
317
318

Status Codes
319

320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
- <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": [
        {
340
341
342
343
344
345
346
        "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
347
348
        },
        {
349
350
351
352
353
354
355
356
357
        "by_me":32.4,
        "days_left":"220",
        "free":67.6,
        "pid":"DD-1-1",
        "resource_type":"Barbora CPU",
        "total":100.0,
        "used":32.4
        },

358
359
      ],
      "me_as_pi": [
360
361
362
363
364
        {"login":"johnsm",
        "pid":"DD-13-6",
        "resource_type":"Legacy Normalized Core Hours",
        "total":7470000.0,
        "usage":35851.9
365
        },
366
367
368
369
370
        {"login":"johnsm",
        "pid":"DD-1-1",
        "resource_type":"Barbora CPU",
        "total":100.0,
        "usage":32.4
371
372
373
        },
      ]
    }
scs-ror's avatar
scs-ror committed
374
375
376
377
378
379

<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.

scs-ror's avatar
scs-ror committed
380
381
382
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4imotd" class="reference external">it4imotd</a>

383
Query Parameters
384

385
386
387
388
389
- **notice** – returns only notice messages

- **important** – returns only important messages

- **all** – returns all messages
390

391
Response JSON Object
392

393
394
395
396
397
398
399
400
- **author** (*string*) – author of the message

- **category** (*string*) – message category

- **created\_at** (*string*) – creation date

- **dateEfficiency** (*string*) – effective date

401
- **dateExpiration** (*string*) – expiration date
402
403
404

- **dateModification** (*string*) – date the message was modified

405
- **deleted\_at** (*string*) – date the message was deleted
406

407
- **id** (*int*) – message id
408
409
410

- **messageBody** (*string*) – the text of the message

411
- **state** (*string*) – obsolete, no longer used
412
413
414

- **title** (*string*) – the title of the message

415
- **typeMotd** (*string*) – obsolete, no longer used
416

417
- **updated\_at** (*string*) – date of the list’s last update
418

419
Status Codes
420

421
422
423
424
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
- <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"
      }
    ]
scs-ror's avatar
scs-ror committed
455
456
457
458
459

<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.
460

461
Response JSON Object
462

463
464
465
- **message** (*string*) – reply message ‘pong’

Status Codes
466

467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
- <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"
    }
scs-ror's avatar
scs-ror committed
482

483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
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
<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
        }
      ]

539
540
541
542
543
<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.

544
545
Terminal implementation is available at
<a href="https://pypi.org/project/it4i.portal.clients/#it4iuserfsusage" class="reference external">it4iuserfsusage</a>
546
547
548
549
550
551
552

Request JSON Object

- **login** (*string*) – account id

- **it4ifreetoken** (*string*) – token

553
- **cluster** (*string*) – cluster name or ‘all’
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602

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

scs-ror's avatar
scs-ror committed
603
604
605
<a name="get--api-v1-version" class="headerlink" title="Permalink to this definition"></a>
 **GET /api/v1/version**

606
Returns basic information about the API.
607

608
Response JSON Object
609

610
611
- **hostname** (*string*) – system hostname

612
- **revision** (*string*) – API revision / build time
613

614
- **version** (*string*) – API version
615
616

Status Codes
617

618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
- <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"
    }