API Documentation_public
=============================================================================================
Implements API for IT4I SCS Information System.
- api revision: `9eb0678f / 2017-12-08 11:06:12 +0100`
- api version: `0.9-11-g9eb0678`
- apidoc building date: `2017-12-08 15:01:48 +0100`
Summary
--------------------------------------------------------------
Resource | Operation | Description
------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------| ----------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
check-access | [POST /api/v1/check-access](#post--api-v1-check-access) | Access check to queue
dedicated-time | [GET /api/v1/dedicated-time/(cluster\_type)](#get--api-v1-dedicated-time-cluster_type) | HPC dedicated time
it4ifree | [POST /api/v1/it4ifree/(login)](#post--api-v1-it4ifree-login) | Free account resources
motd | [GET /api/v1/motd/(category)](#get--api-v1-motd-category) | SCS messages of the day
ping | [GET /api/v1/ping](#get--api-v1-ping) | Connection test
version | [GET /api/v1/version](#get--api-v1-version) | API version
API Details
----------------------------------------------------------------------
`POST /api/v1/check-access` {#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:
- [200
OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
– 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."
<!-- -->
`GET /api/v1/dedicated-time/`(*cluster\_type*) {#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:
- [200
OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
– no error
- [405 Method Not
Allowed](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6)
– invalid requested query parameter
**Example request**:
curl -i curl 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*) {#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
<https://docs.it4i.cz/salomon/resources-allocation-policy/#normalized-core-hours-nch>
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:
- [200
OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
– no error
- [405 Method Not
Allowed](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6)
– 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,
"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*) {#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:
- [200
OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)
– no error
- [405 Method Not
Allowed](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6)
– 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"
}
]
<!-- -->
`GET /api/v1/ping` {#get--api-v1-ping}
: A service for testing connection to API.
--------------- -----------------------------------------------------------------------------------------------------------------
Status Codes: - [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – 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"
}
<!-- -->
`GET /api/v1/version` {#get--api-v1-version}
: Returns basic information about API.
--------------- -----------------------------------------------------------------------------------------------------------------
Status Codes: - [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – 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"
}
©2017, IT4Innovations. | Powered by [Sphinx
1.5.6](http://sphinx-doc.org/) & [Alabaster
0.7.10](https://github.com/bitprophet/alabaster)