summaryrefslogtreecommitdiffstats
path: root/documentation/api/README.md
diff options
context:
space:
mode:
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.