Skip to content

Changes

Page history
Update REST API Documentation authored by Jeroen Depuydt's avatar Jeroen Depuydt
Show whitespace changes
Inline Side-by-side
REST-API-Documentation.md
View page @ 16599e97
......@@ -25,11 +25,12 @@ The public part of the REST-API has the following URL-Syntax:<br>
`<host>:<port>/public/...`<br>
For requests at the path, it is not necessary to use a token for authentication.
For these requests, no authentication is required.
___
### <a name="login"></a> 2.1 Login
Receives the login informations and tries to authenticate the user. Returns the token, which can be used for the whole session. The token is valid for one hour. In addition it returns the display-name and the mail of the user.
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**
......@@ -39,11 +40,11 @@ ___
`POST`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
......@@ -87,7 +88,7 @@ ___
___
### <a name="register"></a> 2.2 Register
Receives the informations to register a new user. Returns the json object of the new json if the registration was successful.
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**
......@@ -97,11 +98,11 @@ ___
`POST`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
......@@ -145,9 +146,10 @@ ___
___
## <a name="api"></a> 3. API
This is the none public part of the API. To perform the requests you have to authenticate. For that a `Bearer` token is passed in the `Authorization` part of the request. If the request is allowed, depends on the scope of the token. See the table below for the different types of the token.<br/>
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** | **When created** |
| **Scope** | **Explanation** | **Expiration** | **Who is authenticated** | **Amount** | **Creation** |
|:------------------:|:-------------------------------------------------------------------------------------------:|:----------:|:---------------------------------------------:|:-----------------:|:-------------------------------:|
| **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 |
......@@ -155,7 +157,8 @@ This is the none public part of the API. To perform the requests you have to aut
The URL of the request has the following pattern:<br/>
`<host>:<port>/api/<version>/...`
There are several general error codes for the authorization.<br/>
There are several general error codes for the authorization:<br/>
**Error Response:**
* **Code:** 403 `FORBIDDEN` <br>
......@@ -176,8 +179,8 @@ There are several general error codes for the authorization.<br/>
___
### <a name="get_all_cems"></a> 3.1 Get all CEMS
A request to get all CEMS, which are connected to the user.
### <a name="get_all_cems"></a> 3.1 Get all CEMSs
This request gets all CEMSs that are connected to a certain user.
**URL**
......@@ -223,7 +226,7 @@ ___
**Content:**
```json
"You dont have the permission for the request"
"You don't have the permission for the request"
```
* **Code:** 404 `NOT FOUND` <br>
......@@ -236,9 +239,9 @@ ___
___
### <a name="get_ssid"></a> 3.2 Get SSIDs of CEMS
A request to get all SSIDs of a certain CEMS. <br/>
The Get SSIDs request lists all SSIDs of a certain CEMS. <br/>
**Note**<br/>
It is possible that the this request needs more time then a normal request, because it needs to wait for the responds of the CEMS.
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**
......@@ -252,14 +255,14 @@ It is possible that the this request needs more time then a normal request, beca
`user`
**URL Params**
**URL Parameters**
* **Required:**
```javascript
cems_uid=[string]
```
**Data Params**
**Data Parameters**
None
......@@ -301,7 +304,7 @@ It is possible that the this request needs more time then a normal request, beca
___
### <a name="register_sensor"></a> 3.3 Register a sensor
Use this request to register a sensor to a CEMS.
This request is used to register a sensor to a CEMS.
**URL**
......@@ -315,11 +318,11 @@ Use this request to register a sensor to a CEMS.
`cems_io`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
```javascrip
......@@ -366,7 +369,7 @@ Use this request to register a sensor to a CEMS.
___
### <a name="post_sensor_value"></a> 3.4 Post sensor value
With this request it is possible to add a sensor value to the database of the backend.
This request allows you to add a sensor value to the database of the back end.
**URL**
......@@ -380,11 +383,11 @@ With this request it is possible to add a sensor value to the database of the ba
`cems_io`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
```javascript
......@@ -437,7 +440,7 @@ With this request it is possible to add a sensor value to the database of the ba
___
### <a name="register_cems"></a> 3.5 Register CEMS
A request to add a CEMS to the backend.
This request adds a CEMS to the back end.
**URL**
......@@ -451,11 +454,11 @@ A request to add a CEMS to the backend.
`secure_provisioner`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
```javascript
......@@ -495,7 +498,7 @@ A request to add a CEMS to the backend.
___
### <a name="get_all_values"></a> 3.6 Get all sensor values
Request, which returns all sensor values of a user.
This request returns all sensor values of a given user.
**URL**
......@@ -509,11 +512,11 @@ Request, which returns all sensor values of a user.
`user`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
`None`
......@@ -564,7 +567,7 @@ Request, which returns all sensor values of a user.
__
### <a name="setup_wifi"></a> 3.7 Setup CEMS WiFi
Request to post all needed informations to setup the wifi of a CEMS.
Request to post all needed information to set up the WiFi connection of a CEMS.
**URL**
......@@ -578,11 +581,11 @@ Request to post all needed informations to setup the wifi of a CEMS.
`user`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
......@@ -621,7 +624,7 @@ Request to post all needed informations to setup the wifi of a CEMS.
___
### <a name="set_ssids"></a> 3.8 Set SSIDs for CEMS
The CEMS can set the current SSIDs of itself.
This request allows the CEMS to send all available SSIDs to the back end.
**URL**
......@@ -635,11 +638,11 @@ The CEMS can set the current SSIDs of itself.
`cems_io`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
```javascript
......@@ -653,7 +656,7 @@ The CEMS can set the current SSIDs of itself.
```
**Note:**
Only the ssid part of the wlan is used.
Only the SSID part of the wlan is used.
**Success Response:**
* **Code:** 200 `SUCCESS`<br />
......@@ -686,7 +689,7 @@ The CEMS can set the current SSIDs of itself.
___
### <a name="connect_cems"></a> 3.9 Connect CEMS to user
With this request it is possible to add a sensor value to the database of the backend.
This request connects a CEMS to a user in the back end.
**URL**
......@@ -700,11 +703,11 @@ With this request it is possible to add a sensor value to the database of the ba
`user`
**URL Params**
**URL Parameters**
`None`
**Data Params**
**Data Parameters**
* **Required:**
```javascript
......