Skip to content
Snippets Groups Projects
Commit cf32111b authored by Marek Chrastina's avatar Marek Chrastina
Browse files

is/scs-api#4 Added apidocs

parent 6b5876fe
No related branches found
No related tags found
6 merge requests!368Update prace.md to document the change from qprace to qprod as the default...,!367Update prace.md to document the change from qprace to qprod as the default...,!366Update prace.md to document the change from qprace to qprod as the default...,!323extended-acls-storage-section,!196Master,!178Apidocs
Hide whitespace changes
Inline Side-by-side
Showing
with 379 additions and 0 deletions
docs.it4i/apidocs.md 0 → 100644
+ 379
− 0
View file @ cf32111b
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)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment