<aside> <img src="/icons/promoted_red.svg" alt="/icons/promoted_red.svg" width="40px" /> Home | Standards | Module | Hilfe

</aside>

Einleitung

Dieses Dokument stellt keine ausführliche Beschreibung der Schnittstelle mit allen möglichen Parametern dar. Es dient eher als Kurzreferenz und enthält die wichtigsten Anfragen/Antworten. Beispielsweise enthalten alle Antworten eine 'message', welche aber für die Funktionsweise nicht relevant ist, bzw. nur im Fehlerfall zur Fehlersuche hilfreich ist. In den Beispiel-Container werden optionale Blöcke durch () markiert. Gibt es für einen bestimmten Parameter mehrere mögliche Auswahlen werden diese durch [ Auswahl 1 | Auswahl 2 | ... ] gekennzeichnet.

Zugang

Die Schnittstelle wird, sofern nicht anders kommuniziert, über die folgende ULR aufgerufen. https://xxx/external_api/external_api.php. 'xxx' steht dabei für die URL ihrer Installation. Für die Nutzung ist es erforderlich, dass die externe API in der entsprechenden Installation aktiviert ist und man über gültige Zugangsdaten verfügen. Alle Anfragen werden als JSON-konforme Strings an die API gesendet (im Content des HTTP-Requests). Es gilt darauf zu achten, dass es vorher keine Konvertierung oder sonstige Formatierungen gibt, da dies bei der Auswertung zu einem Fehler führen kann.

Fehlerbehandlung

Die Schnittstelle wird immer ein JSON-Container als Antwort zurücksenden. Sollten Fehler aufgetreten sein, wird die Antwort immer die folgende Struktur haben.

{
    "state": false,
    "message": "xxx",
    "code": "x"
}

Ob ein Fehler aufgetreten ist, lässt sich am einfachsten anhand des 'state' prüfen. Ist dieser 'false', liegt ein Fehler vor. ist dies der Fall gibt es auch immer den Parameter 'message'. Dieser enthält einen Text, welcher die aufgetretenen Fehler beschreibt. Diese könnten beispielsweise sein:

• “Missing parameter: xxx”: “xxx” steht hierbei für einen Pflicht-Parameter in der Anfrage, welcher gefehlt hat.
• “Permission denied”: in dem Fall hat man für die gewählte 'Aktion' nicht die notwendigen Berechtigungen.

Außerdem kann man den 'code' prüfen, eine Auflistung aller Codes befindet sich im Anhang.

Authentifizierung

Bevor man irgendwelche Abfragen an die API senden kann muss man sich authentifizieren. Dazu muss die folgenden Anfrage senden. Die Felder „user“ und „password“ müssen mit den entsprechenden Daten befüllt werden.

{
    "function": "authentication",
    "user": "xxx",
    "password": "xxx"
}

War die Authenfizierung erfolgreich, bekommt man die Antwort (2) vom der API zurück. Wichtig ist hier der „token“, diesen muss man bei allen weiteren Abfragen mitsenden. Nach der „expire\_time“ läuft dieser Token automatisch ab und eine erneute Authentifizierung ist erforderlich.

{
    "state": true,
    "token": "xxx",
    "expire_time": "YYYY-MM-DD HH:MM:SS"
}

Eigene Rechte einsehen

Um sich Informationen über die eigenen Rechte zu holen muss folgender Aufruf an die Schnittstelle gesendet werden.

{
    "token": "xxx",
    "function": "return_rights"
}