From 58d0657657122c644231346bad5c6e9a26dd6bae Mon Sep 17 00:00:00 2001
From: Gulliver <gulliver@traumkristalle.net>
Date: Mon, 31 May 2021 21:56:02 +0200
Subject: [PATCH] added overview rest API

---
 doc/source/architecture/overview.rst | 193 +++++++++++++++++++++++++++
 1 file changed, 193 insertions(+)

diff --git a/doc/source/architecture/overview.rst b/doc/source/architecture/overview.rst
index a148fd4..fce9159 100644
--- a/doc/source/architecture/overview.rst
+++ b/doc/source/architecture/overview.rst
@@ -34,6 +34,9 @@ Technisch
 Systemkontext
 =============
 
+Systemkontext Backend
+*********************
+
 .. uml:: systemcontext.plantuml.txt
 
 Use cases
@@ -50,3 +53,193 @@ Datenmodell
 
 .. uml:: erdmodel.plantuml.txt
 
+Überblick Rest API
+==================
+
+Authentifizierung
+*****************
+
+HTTP Bearer Token. Wird vom Backend verwaltet. Es gibt eine konfigurierbare, maximale Gültigkeit für einen Token.
+
+Allgemeine Antworten:
+
+* 401: Anfrage ohne Token
+* 403: Token abgelaufen oder ungültig
+
+Authorisierung
+**************
+
+* Zugriff nur mit Login
+* Jeder eingloggte Benutzer darf alles sehen
+* Ein Benutzer darf nur sein eigenes Profil bearbeiten
+
+Endpunkte
+*****************
+
+POST `/users/login` 
+-------------------
+
+Hiermit kann sich ein Benutzer anmelden. Der Endpunkt authentifiziert gegen LDAP.
+
+Anfrage:
+
+.. code-block:: text
+   :linenos:
+
+   {
+      "username": "peter",
+       "password": "asdasd"
+   }
+
+Antwort:
+**Status 200**
+
+Login hat geklappt
+
+
+.. code-block:: json
+
+   {
+      "token": "aSDASDADASDASD"
+   }
+
+**Status 403**
+
+Login hat nicht geklappt. Grund ist Benutzer existiert nicht oder Passwort war falsch. Kein weiterer Text über die API wegen Sicherheit.
+
+DELETE `/users/login`
+---------------------
+
+Markiert den zur Request Authentifizierung verwendeten Token als nicht mehr gültig.
+
+POST `/users/profile`
+---------------------
+
+Speichert ein Profil ab. Übertragene Daten entsprechen #3 im JSON Format.
+
+Anfrage:
+
+.. code-block:: json
+
+   {
+      "profile": {}
+   }
+
+
+Antwort:
+
+**Status 200**
+
+Gespeichert, ok
+
+**Status 400**
+
+Validierung fehlgeschlagen
+
+.. code-block:: json
+
+   {
+      "messages": {
+         "nickname": "Bitte ausfüllen"
+      }
+   }
+
+
+GET `/users/{id}/profile`
+-------------------------
+
+Endpunkt um ein Profil gezielt nach ID abzurufen.
+
+Antwort:
+
+
+**Status 200**
+
+Profil gefunden
+
+.. code-block:: json
+
+   {
+     "profile": {}
+   }
+
+GET `/users/profiles`
+-------------------------
+
+Suche nach Profilen mit Query-Parametern:
+
+* `skill[]=PHP`
+* `page=1` für die Paginierung
+* `page_size=20` Einträge pro Seite
+
+(Liste wird erweitert).
+
+Antwort:
+
+.. code-block:: json
+
+   {
+     "total": 23,
+     "profiles": []
+   }
+
+* `total` Gesamtanzahl der passenden Profile
+* `profils` Liste mit Profilen
+
+GET `/skills`
+-------------------------
+
+Hier können die auswählbaren Fähigkeiten inkl. Autovervollständigung abgerufen werden sowie "Ich Suche".
+
+* `search=an`
+* Es werden 10 Einträge zurückgegeben
+
+Antwort:
+
+.. code-block:: json
+
+   {
+     "skills": [
+        {
+            "id": 23,
+            "name": "Angular"
+        },
+        {
+            "id": 42,
+            "name": "Anforderungs-Management"
+        }
+    ]
+   }
+
+
+GET `/skills/{id}/icon`
+-----------------------
+
+Icon einer Fähigkeit (weils gut ausschaut).
+
+GET `/languages`
+----------------
+
+Abruf der Sprachen.
+
+* `search=fra`
+* Es werden 10 Einträge zurückgegeben
+
+Antwort:
+
+.. code-block:: json
+
+   {
+     "languages": [
+        {
+            "id": 23,
+            "name": "Französisch"
+        }
+     ]
+   }
+
+
+GET `/languages/{id}/icon`
+--------------------------
+
+Icon einer Sprache (weils gut ausschaut).