summaryrefslogtreecommitdiffstats
path: root/documentation/api/collections.md
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/collections.md
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/collections.md')
-rw-r--r--documentation/api/collections.md168
1 files changed, 168 insertions, 0 deletions
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