From dc102d24f0fcb6247388880abc7f3208d0b7a9eb Mon Sep 17 00:00:00 2001 From: Jannik Schönartz Date: Sun, 10 Mar 2019 03:50:32 +0000 Subject: [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 --- documentation/api/README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 documentation/api/README.md (limited to 'documentation/api/README.md') 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:///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 +``` + +> **\** - 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. -- cgit v1.2.3-55-g7522