summaryrefslogtreecommitdiffstats
path: root/documentation/api
diff options
context:
space:
mode:
authorJannik Schönartz2019-03-10 04:50:32 +0100
committerJannik Schönartz2019-03-10 04:50:32 +0100
commitdc102d24f0fcb6247388880abc7f3208d0b7a9eb (patch)
treef5c7af2f8cb217488052b71978f45a667d03b363 /documentation/api
parent[ipxe] Add parameter to api how many lines the response should send and adjus... (diff)
downloadbas-dc102d24f0fcb6247388880abc7f3208d0b7a9eb.tar.gz
bas-dc102d24f0fcb6247388880abc7f3208d0b7a9eb.tar.xz
bas-dc102d24f0fcb6247388880abc7f3208d0b7a9eb.zip
[documentation] Add documentation site
Override css (Design the topbar & site) <-- A lot of Udo's help Create structure for the differen pages Start writing the installation Write the getting started API site Write documentation of the authentication api Write documentation of the setup api
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