summaryrefslogtreecommitdiffstats
path: root/documentation/api/README.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/README.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/README.md')
-rw-r--r--documentation/api/README.md57
1 files changed, 57 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.