|
|
| (18 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) |
| Zeile 1: |
Zeile 1: |
| {{Kostenpflichtige Module}}
| | #WEITERLEITUNG [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Endpunkt]] |
| | |
| =Endpunkte=
| |
| | |
| Ein '''Endpunkt''' definiert eine Adresse, über die der REST-Server eine konkrete Funktion anbietet. Hinter jedem Endpunkt steht entweder ein OBS-Skript (Standardfall) oder ein WebHook (Einmal-Antwort für asynchrone Rückrufe).
| |
| | |
| ==Aufruf==
| |
| | |
| '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Endpunkte'''
| |
| | |
| ==Felder==
| |
| | |
| {| class="wikitable"
| |
| ! Feld !! Beschreibung
| |
| |-
| |
| | Endpunkt || Hauptname, erster Pfad-Bestandteil nach der Hostadresse (Pflichtfeld)
| |
| |-
| |
| | Sub-URL || Optionaler zweiter Pfad-Bestandteil, z.B. ''mobile'', ''office''
| |
| |-
| |
| | Version || Versionsbezeichner, z.B. ''v1'', ''v1.0'', ''v2''
| |
| |-
| |
| | Server || Zuordnung zu einem Server-Profil. Der Endpunkt ist nur über dieses Profil erreichbar (Pflichtfeld)
| |
| |-
| |
| | Aktiv || Inaktive Endpunkte sind nicht ansprechbar (404)
| |
| |-
| |
| | Info || Freitext zur Dokumentation
| |
| |}
| |
| | |
| ==Adressbildung==
| |
| | |
| Die Adresse setzt sich aus Endpunkt, Sub-URL und Version zusammen:
| |
| | |
| http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]
| |
| | |
| Beispiele:
| |
| | |
| https://api.meinserver.de/kalender/v1
| |
| https://api.meinserver.de/email/mein_konto/v1.0
| |
| | |
| Wird die Sub-URL leer gelassen, verkürzt sich die Adresse auf ''/Endpunkt/Version''.
| |
| | |
| ==Versionierung==
| |
| | |
| Die Versionierung erlaubt es, eine Endpunkt-Funktionalität zu ändern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
| |
| | |
| # Den vorhandenen Endpunkt unverändert lassen, weiterhin aktiv halten.
| |
| # Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen. | |
| # Berechtigungen für die neuen Konsumenten setzen.
| |
| # Wenn alle Konsumenten umgestellt sind, den alten Endpunkt deaktivieren.
| |
| | |
| ==Zuordnung zum Server-Profil==
| |
| | |
| Ein Endpunkt ist immer genau einem Server-Profil zugeordnet. Damit lassen sich z.B. der gleiche Endpunkt-Name auf einem Public-Server (Standard-TLS) und einem Internal-Server (mTLS) parallel betreiben - die jeweils dem Server zugeordneten Endpunkte werden voneinander getrennt. Ein Konsument, der über das Public-Profil zugreift, kann nicht versehentlich die mTLS-Variante ansprechen.
| |
| | |
| ==Berechtigungen==
| |
| | |
| Damit ein Zugang einen Endpunkt aufrufen darf, muss er für diesen Endpunkt freigeschaltet sein. Aus der Endpunkt-Liste den Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste.
| |
| | |
| In der Berechtigungs-Liste:
| |
| | |
| * '''Einfg''' - öffnet die Zugänge-Liste.
| |
| * In der Zugänge-Liste mit '''F5''' einen oder mehrere Zugänge markieren.
| |
| * '''F2''' übernimmt die markierten Zugänge als Berechtigungen.
| |
| | |
| Ohne Markierung wird nur der aktuelle Zugang übernommen.
| |
| | |
| ==Endpunkt-Skript==
| |
| | |
| Aus der Endpunkt-Liste den Endpunkt markieren und '''F7''' drücken. Es öffnet sich der Skript-Editor. Im Skript werden GET-, POST-, PUT-, DELETE- bzw. PATCH-Funktionen implementiert, die der Server bei Aufruf der entsprechenden HTTP-Methode aufruft.
| |
| | |
| Die genaue Skript-Syntax und alle verfügbaren Parameter sind unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] beschrieben.
| |
| | |
| ==WebHooks==
| |
| | |
| Ein Endpunkt kann alternativ als WebHook konfiguriert werden. WebHooks sind '''Einmal-Endpunkte''' - sie werden in der Regel von OBS aus dynamisch für externe Dienste angelegt (z.B. Bezahl-Callbacks). Beim ersten erfolgreichen Aufruf:
| |
| | |
| # Die übergebenen Daten (Query-String oder Request-Body) werden in der Tabelle '''REMOTE_HOOK_URL''' im Feld ''hu_response'' gespeichert.
| |
| # Der Endpunkt wird automatisch aus '''RESTSRV_ENDPOINTS''' gelöscht.
| |
| # Der Server antwortet mit ''{"status": "ok"}''.
| |
| | |
| Damit lassen sich asynchrone Rückrufe sauber konsumieren, ohne dass dauerhaft offene Endpunkte zurückbleiben. Die Anlage und Auswertung eines WebHooks erfolgt typischerweise programmgesteuert über die zugehörigen Helper-Funktionen, nicht über die Endpunkt-Maske.
| |
| | |
| ==Listen-Funktionen==
| |
| | |
| In der Endpunkt-Liste:
| |
| | |
| * '''Einfg''' - neuer Endpunkt
| |
| * '''Return''' - Endpunkt bearbeiten
| |
| * '''F4''' - Sortierung
| |
| * '''F6''' - Berechtigungen verwalten (Zugänge dem Endpunkt zuordnen)
| |
| * '''F7''' - Endpunkt-Skript bearbeiten
| |
| * '''F8''' - Statistik für den Endpunkt
| |
| | |
| ==Cache==
| |
| | |
| Der REST-Server cached das kompilierte Skript pro Endpunkt. Wird das Skript über F7 geändert, ist die neue Version sofort wirksam - der Server erkennt die Änderung am ''sys_date'' und compiliert neu.
| |
| | |
| ==Typische Fehlermeldungen==
| |
| | |
| {| class="wikitable"
| |
| ! Code !! Bedeutung
| |
| |-
| |
| | 404 || Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil
| |
| |-
| |
| | 403 || Keine Berechtigung für die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste)
| |
| |-
| |
| | 401 || API-Key fehlt, ungültig, JWT fehlt oder ist abgelaufen
| |
| |-
| |
| | 500 || Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO
| |
| |}
| |