Skip to content

Changes

Page history
Update Starball REST API Documentation authored by Michael Fischinger's avatar Michael Fischinger
Show whitespace changes
Inline Side-by-side
REST-API-Documentation.md 0 → 100644
View page @ 4e263f94
[[_TOC_]]
___
## 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.
___
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
The public part of the REST-API has the following URL-Syntax:<br>
`<host>:<port>/api/<version>/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.
**URL**
`/public/register`
**Method:**
`POST`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
email=[string]
password=[string]
first_name=[string]
last_name=[string]
```
* **Optional:**
```javascript
address=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"id": 3,
"first_name": "Jon",
"last_name": "Dorian",
"email": "newuser@user.com",
"address": null
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
{ error: "<error message>" }
```
___
## 3. Basic User Authentication
___
### 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.
**URL**
`/login/:username`
**Method:**
`GET`
**URL Parameters**
* **Required:**
```javascript
username=[string]
```
**Data Parameters**
`None`
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"user_token": "eyJhbGciOiJIUzI1NiJ",
"user": {
"email": "test@domain.com",
"name": "Max Mustermann"
}
}
```
**Error Response:**
* **Code:** 404 `NOT FOUND` <br />
**Content:**
```json
{"User not found"}
```
OR
* **Code:** 401 `UNAUTHORIZED` <br />
**Content:**
```json
{"Wrong password"}
```
___
## 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.
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
```
There are several general error codes for the authorization:<br/>
**Error Response:**
* **Code:** 403 `FORBIDDEN` <br>
**Content:**<br/>
`A token has expired`
* **Code:** 403 `FORBIDDEN` <br>
**Content:**<br/>
`The token does not have a valid issuer.`
* **Code:** 403 `FORBIDDEN` <br>
**Content:**<br/>
`The token does not have a valid "issued at" time.`
* **Code:** 401 `UNAUTHORIZED` <br>
**Content:**<br/>
`A token must be passed.`
___
### 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.
**URL**
`/api/v1/register_stams`
**Method:**
`POST`
**Scope:**
`secure_provisioner`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
provisioning_uid=[string]
```
* **Optional:**
```javascript
operator=[string]
publickey=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"stams_token": "eyJhbGciOiJIUzI1NiJ9.eyJleHA"
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
<error_message>
```
* **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.
#### 4.2.1 Add Operator
This request adds an operator to the back end.
**URL**
`/api/v1/add_operator`
**Method:**
`POST`
**Scope:**
`admin`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
user_id=[string]
club_name=[string]
address=[string]
country_id=[string]
city_id=[string]
league_id=[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"
}
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
<error_message>
```
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```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.
___
#### 4.2.2 Connect STAMS to Operator
This request connects a STAMS to a user in the back end.
**URL**
`/api/v1/connect_stams`
**Method:**
`POST`
**Scope:**
`admin`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
stams_uid=[string]
operator_uid=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
<error_message>
```
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"STAMS not found"
```
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"User not found"
```
#### 4.2.3 Add Game
This request adds a game to the back end.
**URL**
`/api/v1/add_game`
**Method:**
`POST`
**Scope:**
`admin`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
gameConfigDTO=[string] // TODO: What does this look like?
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
<error_message>
```
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
___
### 4.3 Operator Scope
#### 4.3.1 Get all STAMSs
This request gets all STAMSs that are connected to a certain operator.
**URL**
`/api/v1/all_stams`
**Method:**
`GET`
**Scope:**
`operator`
**URL Parameters**
`None`
**Data Parameters**
`None`
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
[
{
"display_name": "stams1",
"uid": 1,
"provisioning_uid": "a2381a23c3fe89b3"
},
{
"display_name": "stams2",
"uid": 2,
"provisioning_uid": "f588126773fe9c8d"
}
]
```
**Error Response:**
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
* **Code:** 404 `NOT FOUND` <br>
**Content:**
```json
"User not found"
```
___
#### 4.3.2 Add Coach
This request adds a coach to the back end.
**URL**
`/api/v1/add_coach`
**Method:**
`POST`
**Scope:**
`operator`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
user_id=[string]
club_id=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"coach": {
"coach_id": 1,
"user": {
"email": "fisch@domain.com",
"name": "Mike Mustermann"
}
"club_name":"Union Henndorf",
}
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
<error_message>
```
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
___
### 4.4 Coach Scope
#### 4.4.1 Create Team
This request creats a team on the back end.
**URL**
`/api/v1/teams`
**Method:**
`POST`
**Scope:**
`coach`
**URL Parameters**
`None`
**Data Parameters**
* **Required:**
```javascript
coach_id=[string]
operator_id=[string]
team_name=[string]
```
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
**Content:**
```json
{
"team": {
"team_id": 1,
"coach_id": 2,
"operator_id": 1,
"team_name":"U12 Union Henndorf"
}
}
```
**Error Response:**
* **Code:** 400 `BAD REQUEST` <br>
**Content:**
```json
<error_message>
```
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
___
#### 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.
**URL**
`/api/v1/teams/:team_id/players`
**Method:**
`POST`
**Scope:**
`coach`
**URL Parameters**
`team_id`
**Data Parameters**
* **Required:**
```javascript
user_ids =[array_list[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>
**Content:**
```json
<error_message>
```
* **Code:** 403 `FORBIDDEN` <br>
**Content:**
```json
"You don't have the permission for the request"
```
___
\ No newline at end of file