|
|
| (19 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, ueber die der REST-Server eine konkrete Funktion anbietet. Hinter jedem Endpunkt steht entweder ein OBS-Skript (Standardfall) oder ein WebHook (Einmal-Antwort fuer asynchrone Rueckrufe).
| |
| | |
| ==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 ueber 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, verkuerzt sich die Adresse auf ''/Endpunkt/Version''.
| |
| | |
| ==Versionierung==
| |
| | |
| Die Versionierung erlaubt es, eine Endpunkt-Funktionalitaet zu aendern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
| |
| | |
| # Den vorhandenen Endpunkt unveraendert lassen, weiterhin aktiv halten.
| |
| # Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen. | |
| # Berechtigungen fuer 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 ueber das Public-Profil zugreift, kann nicht versehentlich die mTLS-Variante ansprechen.
| |
| | |
| ==Berechtigungen==
| |
| | |
| Damit ein Zugang einen Endpunkt aufrufen darf, muss er fuer diesen Endpunkt freigeschaltet sein. Aus der Endpunkt-Liste den Endpunkt markieren und '''F6''' druecken. Es oeffnet sich die Berechtigungs-Liste.
| |
| | |
| In der Berechtigungs-Liste:
| |
| | |
| * '''Einfg''' - oeffnet die Zugaenge-Liste.
| |
| * In der Zugaenge-Liste mit '''F5''' einen oder mehrere Zugaenge markieren.
| |
| * '''F2''' uebernimmt die markierten Zugaenge als Berechtigungen.
| |
| | |
| Ohne Markierung wird nur der aktuelle Zugang uebernommen.
| |
| | |
| ==Endpunkt-Skript==
| |
| | |
| Aus der Endpunkt-Liste den Endpunkt markieren und '''F7''' druecken. Es oeffnet 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 verfuegbaren 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 fuer externe Dienste angelegt (z.B. Bezahl-Callbacks). Beim ersten erfolgreichen Aufruf:
| |
| | |
| # Die uebergebenen 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''' geloescht.
| |
| # Der Server antwortet mit ''{"status": "ok"}''.
| |
| | |
| Damit lassen sich asynchrone Rueckrufe sauber konsumieren, ohne dass dauerhaft offene Endpunkte zurueckbleiben. Die Anlage und Auswertung eines WebHooks erfolgt typischerweise programmgesteuert ueber die zugehoerigen Helper-Funktionen, nicht ueber die Endpunkt-Maske.
| |
| | |
| ==Listen-Funktionen==
| |
| | |
| In der Endpunkt-Liste:
| |
| | |
| * '''Einfg''' - neuer Endpunkt
| |
| * '''Return''' - Endpunkt bearbeiten
| |
| * '''F4''' - Sortierung
| |
| * '''F6''' - Berechtigungen verwalten (Zugaenge dem Endpunkt zuordnen)
| |
| * '''F7''' - Endpunkt-Skript bearbeiten
| |
| * '''F8''' - Statistik fuer den Endpunkt
| |
| | |
| ==Cache==
| |
| | |
| Der REST-Server cached das kompilierte Skript pro Endpunkt. Wird das Skript ueber F7 geaendert, ist die neue Version sofort wirksam - der Server erkennt die Aenderung am ''sys_date'' und compiliert neu.
| |
| | |
| ==Typische Fehlermeldungen==
| |
| | |
| {| class="wikitable"
| |
| ! Code !! Bedeutung
| |
| |-
| |
| | 404 || Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil
| |
| |-
| |
| | 403 || Keine Berechtigung fuer die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste)
| |
| |-
| |
| | 401 || API-Key fehlt, ungueltig, JWT fehlt oder ist abgelaufen
| |
| |-
| |
| | 500 || Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO
| |
| |}
| |