From cf32111bc1267c854bc184f97a3c482139afeb69 Mon Sep 17 00:00:00 2001
From: Marek Chrastina <marek.chrastina@vsb.cz>
Date: Fri, 8 Dec 2017 15:13:40 +0100
Subject: [PATCH] is/scs-api#4 Added apidocs
---
docs.it4i/apidocs.md | 379 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 379 insertions(+)
create mode 100644 docs.it4i/apidocs.md
diff --git a/docs.it4i/apidocs.md b/docs.it4i/apidocs.md
new file mode 100644
index 000000000..141eae58d
--- /dev/null
+++ b/docs.it4i/apidocs.md
@@ -0,0 +1,379 @@
+
+
+
+
+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)
+
--
GitLab