Skip to content

Changes

Page history
reset version authored by Michael Fischinger's avatar Michael Fischinger
Show whitespace changes
Inline Side-by-side
REST-API-Documentation.md
View page @ 1fc74c7f
[[_TOC_]]
# Table of Contents
* [1. Introduction](#introduction)
* [2. Public](#public)
* [2.1 Login](#login)
* [2.2 Register](#register)
* [3. API](#api)
* [3.1 Get all CEMS](#get_all_cems)
* [3.2 Get SSIDs of CEMS](#get_ssid)
* [3.3 Register a sensor](#register_sensor)
* [3.4 Post sensor value](#post_sensor_value)
* [3.5 Register CEMS](#register_cems)
* [3.6 Get all sensor values](#get_all_values)
* [3.7 Setup wifi of CEMS](#setup_wifi)
* [3.8 Set SSIDs for CEMS](#set_ssids)
* [3.9 Connect CEMS to user](#connect_cems)
___
## 1. Introduction
This document describes the available REST-requests for the required back end, and is divided in a **Public** and an **API** part. The differences between the two parts is explained in the corresponding chapters.
## <a name="introduction"></a> 1. Introduction
This document describes the available REST-requests for the current state of the back end, and is divided in a **Public** and an **API** part. The differences between the two parts is explained in the corresponding chapters.
___
The service should generally be available following the convention `<host>:<port>/api/<version>/...` e.g. https://api.starball.at:1234/api/v1/ or even without a concrete port such as https://api.starball.at/api/v1/
## 2. Public
## <a name="public"></a> 2. Public
The public part of the REST-API has the following URL-Syntax:<br>
`<host>:<port>/api/<version>/public/...`<br>
`<host>:<port>/public/...`<br>
For these requests, no authentication is required.
___
### 2.2 Register
The register request receives the information needed to register a new user. It returns the JSON object of the new JSON if the registration was successful.
### <a name="login"></a> 2.1 Login
Login receives the login information and tries to authenticate the user. It also returns the token, which can be used for the whole session. This token is valid for one hour.
Login also returns the display name and the email address of the user.
**URL**
`/public/register`
`/public/login`
**Method:**
......@@ -39,14 +51,6 @@ The register request receives the information needed to register a new user. It
```javascript
email=[string]
password=[string]
first_name=[string]
last_name=[string]
```
* **Optional:**
```javascript
address=[string]
```
**Success Response:**
......@@ -56,50 +60,64 @@ The register request receives the information needed to register a new user. It
```json
{
"id": 3,
"first_name": "Jon",
"last_name": "Dorian",
"email": "newuser@user.com",
"address": null
"user_token": "eyJhbGciOiJIUzI1NiJ",
"user": {
"email": "test@domain.com",
"name": "Max Mustermann"
}
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
* **Code:** 404 `NOT FOUND` <br />
**Content:**
```json
{ error: "<error message>" }
{"User not found"}
```
___
## 3. Basic User Authentication
OR
* **Code:** 401 `UNAUTHORIZED` <br />
**Content:**
```json
{"Wrong password"}
```
___
### 3.1 Login
Login receives the login information via HTTP Basic User Authentication and tries to authenticate the user. If it is successful, it returns the token, which can be used for the whole session. This token is valid for one hour.
Login also returns the display name and the email address of the user.
### <a name="register"></a> 2.2 Register
The register request receives the information needed to register a new user. It returns the JSON object of the new JSON if the registration was successful.
**URL**
`/login/:username`
`/public/register`
**Method:**
`GET`
`POST`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
username=[string]
email=[string]
password=[string]
first_name=[string]
last_name=[string]
```
**Data Parameters**
* **Optional:**
`None`
```javascript
address=[string]
```
**Success Response:**
......@@ -108,55 +126,36 @@ Login also returns the display name and the email address of the user.
```json
{
"user_token": "eyJhbGciOiJIUzI1NiJ",
"user": {
"email": "test@domain.com",
"name": "Max Mustermann"
}
"id": 3,
"first_name": "Jon",
"last_name": "Dorian",
"email": "newuser@user.com",
"password": "tester",
"address": null
}
```
**Error Response:**
* **Code:** 404 `NOT FOUND` <br />
**Content:**
```json
{"User not found"}
```
OR
* **Code:** 401 `UNAUTHORIZED` <br />
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
{"Wrong password"}
{ error: "<error message>" }
```
___
## 4. JWT Authentication
In this chapter, the JWT (JSON Web Token) Authentication part of the API is explained. In order to perform following requests, an authentication is required. For that a `Bearer` token is passed in the `Authorization` part of the request. The scope of this token effects the allowance of the request.
## <a name="api"></a> 3. API
In this chapter, the non-public part of the API is explained. In order to perform following requests, an authentication is required. For that a `Bearer` token is passed in the `Authorization` part of the request. The scope of this token effects the allowance of the request.
This table shows the different types of the Bearer token.<br/>
| **Scope** | **Explanation** | **Expiration** | **Who is authenticated** | **Amount** | **Creation** |
|:------------------:|:-------------------------------------------------------------------------------------------:|:----------:|:---------------------------------------------:|:-----------------:|:-------------------------------:|
| **admin** | Token to authenticate all admin requests (except register and login) from the PWA to the back end. | 1h | PWA-Admin-User | 1 for every login | At the login |
| **operator** | Token to authenticate all operator requests (except register and login) from the PWA to the back end. | 1h | PWA-Operator-User | 1 for every login | At the login |
| **coach** | Token to authenticate all coach requests (except register and login) from the PWA to the back end. | 1h | PWA-Coach-User | 1 for every login | At the login |
| **player** | Token to authenticate all player requests (except register and login) from the PWA to the back end. | 1h | PWA-Player-User | 1 for every login | At the login |
| **stams_io** | Token to authenticate the STAMS (Starball Management System) for requests to the backend. | never | STAMS | 1 for every STAMS | At the registration of the STAMS |
| **secure_provisioner** | Token to authenticate the secured provisioner to register a STAMS. | never | Secured provisioner for the STAMS registration | 1 | At the start of the project
**Hint: <br/> The PWA user authentication follows an Top-Down-Approach. This means, that an `admin` user also includes the permissions to access any of the underlying API interfaces of an `operator` a `coach` and a `player` user. An `operator` is allowed to access the API interfaces of a `coach` and a `player` user. And so on.**
<br/>
The URL of the request has the following pattern: `<host>:<port>/api/<version>/...`
**Here is an EXAMPLE for JWT Authentication using curl:**
```
curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://api.starball.at/api/v1/myresource
```
| **user** | Token to authenticate all requests (except register and login) from the PWA to the back end. | 1h | PWA-User | 1 for every login | At the login |
| **cems_io** | Token to authenticate the CEMS for requests to the backend. | never | CEMS | 1 for every cems | At the registration of the CEMS |
| **secure_provisioner** | Token to authenticate the secured provisioner to register a CEMS. | never | Secured provisioner for the CEMS registration | 1 | At the start of the project
The URL of the request has the following pattern:<br/>
`<host>:<port>/api/<version>/...`
There are several general error codes for the authorization:<br/>
......@@ -180,76 +179,136 @@ There are several general error codes for the authorization:<br/>
___
### 4.1 `secure_provisioner` Scope
Each STAMS is automatically and centrally provisioned and set-up before it is sold. This is done within the `secure_provisioner` scope, where the STAMS receives a unique JWT from the Backend Server.
#### 4.1.1 Register STAMS
This request adds a STAMS to the back end.
### <a name="get_all_cems"></a> 3.1 Get all CEMSs
This request gets all CEMSs that are connected to a certain user.
**URL**
`/api/v1/register_stams`
`/api/v1/all_cems`
**Method:**
`POST`
`GET`
**Scope:**
`secure_provisioner`
`user`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
provisioning_uid=[string]
```
* **Optional:**
```javascript
operator=[string]
publickey=[string]
```
`None`
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
[
{
"stams_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHA"
"display_name": "display",
"uid": "ajkkljaw"
},
{
"display_name": "display2",
"uid": "vasdvgasdf"
}
]
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
<error_message>
"You don't have the permission for the request"
```
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"User not found"
```
___
### <a name="get_ssid"></a> 3.2 Get SSIDs of CEMS
The Get SSIDs request lists all SSIDs of a certain CEMS. <br/>
**Note**<br/>
It is possible that the this request needs more time than a normal request, since it needs to wait for the response of the CEMS.
**URL**
`/api/v1/get_ssid`
**Method:**
`GET`
**Scope:**
`user`
**URL Parameters**
* **Required:**
```javascript
cems_uid=[string]
```
**Data Parameters**
None
**Success Response:**
* **Code:** 200 'SUCCESS'<br>
**Content:**
```json
[
"WiFi1",
"WiFi2",
"GuestWiFi"
]
```
**Error Response:**
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
___
### 4.2 Admin Scope
This chapter describes all (for the moment known) Admin requests.
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"User not found"
```
#### 4.2.1 Add Operator
This request adds an operator to the back end.
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"CEMS not found"
```
___
### <a name="register_sensor"></a> 3.3 Register a sensor
This request is used to register a sensor to a CEMS.
**URL**
`/api/v1/add_operator`
`/api/v1/register_sensor`
**Method:**
......@@ -257,7 +316,7 @@ This request adds an operator to the back end.
**Scope:**
`admin`
`cems_io`
**URL Parameters**
......@@ -266,34 +325,26 @@ This request adds an operator to the back end.
**Data Parameters**
* **Required:**
```javascript
user_id=[string]
club_name=[string]
address=[string]
country_id=[string]
city_id=[string]
league_id=[string]
```javascrip
uid=[string]
display_name=[string]
sensor_type=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"operator": {
"operator_id": 1,
"user": {
"email": "test@domain.com",
"name": "Max Mustermann"
}
"club_name":"Union Henndorf",
"address": "Seestraße 12",
"country": "Austria",
"city": "Salzburg"
"league": "1. Landesliga"
}
"id": 7,
"display_name": "New registered Sensor",
"sensor_type": "Humidity",
"cems_box_id": 3,
"uid": 50
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
......@@ -308,16 +359,21 @@ This request adds an operator to the back end.
```json
"You don't have the permission for the request"
```
___
**Hint:** It is suggested that each of the parameters representing an `id` (e.g. `league_id`) also has its own RESTful JSON API interface. For now, it is not possible to estimate any of the possibly required interfaces for the future.
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"CEMS not found"
```
___
#### 4.2.2 Connect STAMS to Operator
This request connects a STAMS to a user in the back end.
### <a name="post_sensor_value"></a> 3.4 Post sensor value
This request allows you to add a sensor value to the database of the back end.
**URL**
`/api/v1/connect_stams`
`/api/v1/post_sensor_values`
**Method:**
......@@ -325,7 +381,7 @@ This request connects a STAMS to a user in the back end.
**Scope:**
`admin`
`cems_io`
**URL Parameters**
......@@ -335,13 +391,23 @@ This request connects a STAMS to a user in the back end.
* **Required:**
```javascript
stams_uid=[string]
operator_uid=[string]
data=[json] (Escaped '"')
timestamp=[string] (In ms from 1.1.1970 (UNIX-TIME)
sensor_uid=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"id": 14,
"data": "{\"value\":\"25\", \"unit\":\"°C\"}",
"sensor_id": 1,
"timestamp": "1528727593510"
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
......@@ -362,22 +428,23 @@ This request connects a STAMS to a user in the back end.
**Content:**
```json
"STAMS not found"
"CEMS not found"
```
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"User not found"
"Sensor not found"
```
___
#### 4.2.3 Add Game
This request adds a game to the back end.
### <a name="register_cems"></a> 3.5 Register CEMS
This request adds a CEMS to the back end.
**URL**
`/api/v1/add_game`
`/api/v1/register_cems`
**Method:**
......@@ -385,7 +452,7 @@ This request adds a game to the back end.
**Scope:**
`admin`
`secure_provisioner`
**URL Parameters**
......@@ -395,11 +462,24 @@ This request adds a game to the back end.
* **Required:**
```javascript
gameConfigDTO=[string] // TODO: What does this look like?
uid=[string]
publickey=[string]
```
* **Optional:**
```javascript
display_name=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"cems_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHA"
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
......@@ -417,14 +497,12 @@ This request adds a game to the back end.
```
___
### 4.3 Operator Scope
#### 4.3.1 Get all STAMSs
This request gets all STAMSs that are connected to a certain operator.
### <a name="get_all_values"></a> 3.6 Get all sensor values
This request returns all sensor values of a given user.
**URL**
`/api/v1/all_stams`
`/api/v1/all_sensor_data`
**Method:**
......@@ -432,7 +510,7 @@ This request gets all STAMSs that are connected to a certain operator.
**Scope:**
`operator`
`user`
**URL Parameters**
......@@ -443,48 +521,57 @@ This request gets all STAMSs that are connected to a certain operator.
`None`
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
[
{
"display_name": "stams1",
"uid": 1,
"provisioning_uid": "a2381a23c3fe89b3"
"data": "{'value':'25', 'unit':'°C'}",
"timestamp": "20180321165642",
"sensor_name": "Temperature Living Room",
"sensor_type": "Temperature",
"cems_name": "display"
},
{
"data": "{'value':'17', 'unit':'°C'}",
"timestamp": "20180319115830",
"sensor_name": "Temperature Kitchen",
"sensor_type": "Temperature",
"cems_name": "display"
},
{
"display_name": "stams2",
"uid": 2,
"provisioning_uid": "f588126773fe9c8d"
"data": "{'value':'19', 'unit':'°C'}",
"timestamp": "20180319115830",
"sensor_name": "Temperature Bathroom",
"sensor_type": "Temperature",
"cems_name": "display2"
}
]
```
**Error Response:**
* **Code:** 403 `FORBIDDEN` <br>
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
"You don't have the permission for the request"
<error_message>
```
* **Code:** 404 `NOT FOUND` <br>
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"User not found"
"You don't have the permission for the request"
```
___
__
#### 4.3.2 Add Coach
This request adds a coach to the back end.
### <a name="setup_wifi"></a> 3.7 Setup CEMS WiFi
Request to post all needed information to set up the WiFi connection of a CEMS.
**URL**
`/api/v1/add_coach`
`/api/v1/setup_cems_wifi`
**Method:**
......@@ -492,61 +579,56 @@ This request adds a coach to the back end.
**Scope:**
`operator`
`user`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
user_id=[string]
club_id=[string]
cems_uid=[string]
ssid=[string]
password=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Error Response:**
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
{
"coach": {
"coach_id": 1,
"user": {
"email": "fisch@domain.com",
"name": "Mike Mustermann"
}
"club_name":"Union Henndorf",
}
}
"You don't have the permission for the request"
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
<error_message>
"User not found"
```
* **Code:** 403 `FORBIDDEN` <br>
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"You don't have the permission for the request"
"CEMS not found"
```
___
### 4.4 Coach Scope
___
#### 4.4.1 Create Team
This request creats a team on the back end.
### <a name="set_ssids"></a> 3.8 Set SSIDs for CEMS
This request allows the CEMS to send all available SSIDs to the back end.
**URL**
`/api/v1/teams`
`/api/v1/set_ssids`
**Method:**
......@@ -554,7 +636,7 @@ This request creats a team on the back end.
**Scope:**
`coach`
`cems_io`
**URL Parameters**
......@@ -564,50 +646,54 @@ This request creats a team on the back end.
* **Required:**
```javascript
coach_id=[string]
operator_id=[string]
team_name=[string]
wlans=[wlan[]]
//wlan is defined as a json with the following parameters:
wlan: {
type=[string]
ssid=[string]
password=[string]
}
```
**Note:**
Only the SSID part of the wlan is used.
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"team": {
"team_id": 1,
"coach_id": 2,
"operator_id": 1,
"team_name":"U12 Union Henndorf"
}
}
[
"WiFi1",
"WiFi2",
"GuestWiFi"
]
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
<error_message>
"You don't have the permission for the request"
```
* **Code:** 403 `FORBIDDEN` <br>
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"You don't have the permission for the request"
"CEMS not found"
```
___
#### 4.4.1 Add Player(s) to Team
This request adds players to a team.
___
**Hint:** The Player Management of a Team is a demonstrative example, where the API will probably require several HTTP Methods (POST, PUT, DELETE, GET) on individual URLs. Even if only the POST method is described in detail in the following, it would be very helpful if developers think about the USE CASE and not only about concrete API requirements while developing. Further methods can therefore follow the patterns of the given examples.
### <a name="connect_cems"></a> 3.9 Connect CEMS to user
This request connects a CEMS to a user in the back end.
**URL**
`/api/v1/teams/:team_id/players`
`/api/v1/connect_cems`
**Method:**
......@@ -615,49 +701,22 @@ This request adds players to a team.
**Scope:**
`coach`
`user`
**URL Parameters**
`team_id`
`None`
**Data Parameters**
* **Required:**
```javascript
user_ids =[array_list[string]]
cems_uid=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"team": {
"team_id": 1,
"coach_id": 2,
"operator_id": 1,
"team_name":"U12 Union Henndorf"
"players": [
{
"id": 3,
"first_name": "Jon",
"last_name": "Dorian",
"email": "newuser@user.com",
"address": null
},
{
"id": 4,
"first_name": "Max",
"last_name": "Neukirchner",
"email": "alterfuchs@user.com",
"address": null
}
]
}
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
......@@ -673,4 +732,17 @@ This request adds players to a team.
```json
"You don't have the permission for the request"
```
___
\ No newline at end of file
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"CEMS not found"
```
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"User not found"
```