Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Endpunkte: Unterschied zwischen den Versionen

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Weiterleitung auf Pflege#Endpunkt, Inhalt in die Seite Pflege übernommen [Volltext ersetzt]
Markierung: Neue Weiterleitung
 
(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
|}

Aktuelle Version vom 17. November 2026, 11:53 Uhr