summaryrefslogtreecommitdiffstats
path: root/documentation/api
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/api')
-rw-r--r--documentation/api/README.md57
-rw-r--r--documentation/api/collections.md168
2 files changed, 225 insertions, 0 deletions
diff --git a/documentation/api/README.md b/documentation/api/README.md
new file mode 100644
index 0000000..f84cdf5
--- /dev/null
+++ b/documentation/api/README.md
@@ -0,0 +1,57 @@
+# Getting Started
+The Api can be called under the following address:
+```
+https://<domain_bss>/api/
+```
+The collections and resources are described in the [Collections](/api/collections.md) section.
+
+## Authorization
+Some collections need authentication while other can be called without.
+To authenticate a request you have to send the json web token to the backend.\
+There are two way to do so
+* **Authorization Header**\
+Set the *Bearer* token in the *Authorization* header.
+```
+Authorization: Bearer <jsonwebtoken>
+```
+
+> **\<jsonwebtoken\>** - Full json web token in the form header.payload.signature.
+
+* **Cookies**\
+To prevent that the Javascript code of the website has access to the full jwt the token is splitted in two seperate cookies.
+ * jwt\_hp - Normal cookie with the header and payload of the jwt as value.
+ * jwt\_s - HTTP only cookie with the signature as value.
+
+To get the token use the login method from the [api/authentication](/api/collections.html#authentication).
+
+## Return values
+The API returns data always in JSON format.
+If the request was successfull it will return status code 200 and the requested data.
+* [200 - OK](https://httpstatuses.com/200)\
+Request was successfull. Optional the response has an json object with the data included.
+
+If a request is not successfull it will set a html status code and return a json object with a status and an error message included.
+```json
+{
+ "error": "",
+ "message": ""
+}
+```
+* [400 - Bad Request](https://httpstatuses.com/400)\
+The request sent to the server was incorrect. (Parameter missing, ...)
+* [401 - Unauthorized](https://httpstatuses.com/401)\
+The client which sent the request to the server wasn't authorized enough. (Invalid token, token missing, ...)
+* [403 - Forbidden](https://httpstatuses.com/403)\
+The authorized client doesn't have enough permission.
+* [404 - Not Found](https://httpstatuses.com/404)\
+The requested resource was not found. (User not found, ...)
+* [500 - Internal Server Error](https://httpstatuses.com/500)\
+Server side error. (Hash errors, ...)
+* [501 - Not Implemented](https://httpstatuses.com/501)\
+The resource doesn't have the requested methods. (Backend doesn't have the method implemented)
+
+If an authenticated request doesn't pass the middleware one of the following error can occur
+* **401 - Unauthorized**
+ * TOKEN\_INVALID - The provided token is invalid.
+ * TOKEN\_INVALID - The token is from an invalid userid.
+ * TOKEN\_MISSING - This service requires a token.
diff --git a/documentation/api/collections.md b/documentation/api/collections.md
new file mode 100644
index 0000000..301a0bb
--- /dev/null
+++ b/documentation/api/collections.md
@@ -0,0 +1,168 @@
+# Collections
+Collections can be called with the api url append with the resource name.
+```
+https://<domain_bss>/api/<collection>/<resource>
+```
+```
+https://<domain_bas>/api/<collection>/:id/<resource>
+```
+
+## Authentication
+The authentication handles the authentication processes like the initial setup, login and logout methods.
+```
+https://<domain_bas>/api/authentication/
+```
+
+### Token Login
+Login method to get a json web token (jwt) for the Authorization header, to make authenticated api calls.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/authentication/token
+
+POST Body
+{
+ "username": "<username>",
+ "password": "<password>"
+}
+```
+
+> **\<username\>**\* - Login name of the user's account.\
+> **\<password\>**\* - Corresponding password to the user's account.\
+> \* Required
+
+**Response**
+* **200 - OK**
+```json
+{
+ "token": "<token>"
+}
+```
+
+> **\<token\>** - Json web token (jwt)
+
+* **400 - Bad Request**
+ * INVALID\_USERNAME - Username does not fullfill the requirements. (No whitespaces)
+ * PASSWORD\_MISSING - This services requires a password.
+ * USER\_MISSING - This service requires an username.
+* **401 - Unauthorized**
+ * PASSWORD\_INVALID - The provided password is invalid.
+* **404 - Not Found**
+ * USER\_NOTFOUND - User does not exist.
+* **500 - Internal Server Error**
+ * DATABASE\_HASH\_INVALID - The hash in the database is corrupted.
+ * INVALID\_UNRECOGNIZED\_HASH - This hash was not made with secure-password. Attempt legacy algorithm.
+ * JWT\_ERROR - Jwt sign failed.
+ * PASSWORD\_REHASH\_ERROR - Rehashing the password failed.
+ * PASSWORD\_VERIFY\_ERROR - Verifying the password failed.
+
+### Cookie Login
+Login method which sets the *jwt_hp* and *jwt_s* cookie.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/authentication/cookies
+
+POST Body
+{
+ "username": "<username>",
+ "password": "<password>"
+}
+```
+
+> **\<username\>**\* - Login name of the user's account.\
+> **\<password\>**\* - Corresponding password to the user's account.\
+> \* Required
+
+**Response**
+* **200 - OK**
+
+| Name | Value | httpOnly | secure |
+| ------- | ------------------------ |:---------:|:------:|
+| jwt\_hp | <token\_header\_payload> | false | true |
+| jwt\_s | <token\_signature> | true | true |
+
+
+
+### Logout
+Deletes the cookies *jwt_hp* and *jwt_s* from the client.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/authentication/logout
+```
+
+**Response**
+* **200 - OK**
+
+## Setup
+### Status
+Returns wheather the unauthorized user (root account) creation can be executed.
+
+**Request**
+```
+GET-Request - unauthorized
+https://<domain_bas>/api/status
+```
+
+**Response**
+* **200 - OK**
+* **403 - Forbidden**
+ * USERTABLE\_NOT\_EMPTY - The user table is not empty, unauthorized creation is forbidden.
+
+### Create Root Account
+Creates the initial root account with superadmin priviliges.\
+This request is only permitted when the user table is empty.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/setup
+
+body {
+ "username": "<username>",
+ "password": "<password>",
+ "name": "<name>",
+ "email": "<email>"
+}
+```
+
+> **\<username\>**\* - Login name of the user's account.\
+> **\<password\>**\* - Corresponding password to the user's account.\
+> **\<name\>** - Full name of the user.\
+> **\<email\>** - Email of the user.\
+> \* Required
+
+**Response**
+* **200 - OK**
+* **400 - Bad Request**
+ * INVALID\_USERNAME - Username does not fullfill the requirements. (No whitespaces)
+ * PASSWORD\_MISSING - This services requires a password.
+ * PASSWORD\_REQUIREMENTS - The password requirements are not fullfilled.
+ * USER\_MISSING - This service requires an username.
+* **401 - Unauthorized**
+ * PASSWORD\_INVALID - The provided password is invalid.
+* **403 - Forbidden**
+ * USERTABLE\_NOT\_EMPTY - The user table is not empty, unauthorized creation is forbidden.
+* **500 - Internal Server Error**
+ * DATABASE\_HASH\_INVALID - The hash in the database is corrupted.
+ * INVALID\_UNRECOGNIZED\_HASH - This hash was not made with secure-password. Attempt legacy algorithm.
+ * PASSWORD\_HASH\_ERROR - Hashing the password failed.
+ * PASSWORD\_REHASH\_ERROR - Rehashing the password failed.
+ * PASSWORD\_VERIFY\_ERROR - Verifying the password failed.
+ * USER\_ALREADY\_EXISTS - The provided username already exists.
+ * USER\_CREATE\_ERROR - User could not be created.
+
+## Backends
+## Backend Types
+## Clients
+## Configloader
+## Configuratior
+## Groups
+## Ipxe
+## Permissions
+## Roles
+## Users \ No newline at end of file