summaryrefslogtreecommitdiffstats
path: root/documentation/de/api/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/de/api/README.md')
-rw-r--r--documentation/de/api/README.md57
1 files changed, 57 insertions, 0 deletions
diff --git a/documentation/de/api/README.md b/documentation/de/api/README.md
new file mode 100644
index 0000000..cda83b4
--- /dev/null
+++ b/documentation/de/api/README.md
@@ -0,0 +1,57 @@
+# Erste Schritte
+Die API kann unter folgender Adresse aufgerufen werden:
+```
+https://<domain_bss>/api/
+```
+Die Sammlungen und Ressourcen werden im Abschnitt [Sammlungen](/de/api/collections.md) beschrieben.
+
+## Autorisierung
+Einige Sammlungen benötigen eine Authentifizierung, während andere ohne aufgerufen werden können.
+Um eine Anfrage zu authentifizieren, müssen Sie den Json-Web-Token an das Backend senden.
+Es gibt zwei Möglichkeiten, dies zu tun
+* **Authorization Header**\
+Durch setzen des *Bearer* token im *Authorization* header.
+```
+Authorization: Bearer <jsonwebtoken>
+```
+
+> **\<jsonwebtoken\>** - Vollständiger json web token in der Form: header.payload.signature.
+
+* **Cookies**\
+Um zu verhindern, dass der Javascript-Code der Website Zugriff auf den vollständige Jwt hat, wird der Token in zwei separate Cookies aufgeteilt
+ * jwt\_hp - Normaler Cookie mit dem Header und Payload des Jwt als Wert.
+ * jwt\_s - HTTP-only Cookie mit der Signature als Wert.
+
+Um den Token zu erhalten, verwenden Sie die Anmeldemethode aus der [API/Authentifizierung](/de/api/collections.html#authentication).
+
+## Rückgabewerte
+Die API gibt Daten immer im JSON-Format zurück.
+Wenn die Anforderung erfolgreich war, wird der Statuscode 200 und die angeforderten Daten zurückgegeben.
+* [200 - OK](https://httpstatuses.com/200)\
+Die Anfrage war erfolgreich. Optional enthält die Antwort ein Json-Objekt mit den enthaltenen Daten.
+
+Wenn eine Anforderung nicht erfolgreich ist, setzt sie einen HTML-Statuscode und gibt ein Json-Objekt mit einem Status und einer Fehlernachricht zurück.
+```json
+{
+ "error": "",
+ "message": ""
+}
+```
+* [400 - Bad Request](https://httpstatuses.com/400)\
+Die an den Server gesendete Anfrage war ungültig. (Parameter fehlt, ...)
+* [401 - Unauthorized](https://httpstatuses.com/401)\
+Der Client, der die Anfrage an den Server gesendet hat, war nicht ausreichend autorisiert. (Ungültiger Token, Token fehlt, ...)
+* [403 - Forbidden](https://httpstatuses.com/403)\
+Der autorisierte Client verfügt nicht über ausreichende Berechtigungen.
+* [404 - Not Found](https://httpstatuses.com/404)\
+Die angeforderte Ressource wurde nicht gefunden. (Benutzer wurde nicht gefunden, ...)
+* [500 - Internal Server Error](https://httpstatuses.com/500)\
+Serverseitiger Fehler. (Hash-Fehler, ...)
+* [501 - Not Implemented](https://httpstatuses.com/501)\
+Die Ressource verfügt nicht über die angeforderten Methoden. (Das Backend hat die Methode nicht implementiert)
+
+Wenn eine Anfrage, die eine Authentifizierung benötigt, nicht hinreichend Authentifiziert ist, können folgende Fehler auftreten
+* **401 - Unauthorized**
+ * TOKEN\_INVALID - Der angegebene Token ist ungültig.
+ * TOKEN\_INVALID - Der Token stammt von einer ungültigen Benutzer-ID.
+ * TOKEN\_MISSING - Dieser Dienst erfordert einen Token.