Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Typ Maske mit Feldern/Tasten aus Maske; Fehlercodes und Idempotenz durch Links ersetzt; WebHooks, Pfad-Parameter, Caching korrigiert; Historie entfernt [Volltext ersetzt]
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Endpunkte nach OBS/Kostenpflichtige Module/REST-Server/Endpunkte: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
(kein Unterschied)

Version vom 17. November 2026, 07:12 Uhr

Endpunkte

Ein Endpunkt stellt eine Adresse bereit, über die der REST-Server eine Funktion anbietet. Hinter jedem Endpunkt steht ein OBS-Skript oder ein WebHook. So veröffentlichen Sie genau die Daten und Vorgänge, die eine Anwendung braucht, und vergeben die Rechte je Adresse. Sie erreichen die Endpunkte über Stammdaten → Z Weitere Stammdaten → REST-Server → Endpunkte.

Liste

Die Liste zeigt alle Endpunkte mit Pfad (dem Pfad-Template) und Serv (der Nummer des Server-Profils). Aktive Endpunkte erscheinen fett.

Tasten und Schaltflächen

Taste Funktion
Einfg Legt einen neuen Endpunkt an.
 ↩ Enter Öffnet den markierten Endpunkt in der Eingabemaske.
F4 Wählt die Sortierung.
F6 Schaltfläche F6 Zugang: öffnet die Liste der Zugänge, die diesen Endpunkt nutzen dürfen, siehe Zugriffskontrolle.
F7 Schaltfläche F7 Script: öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt Scripting.
F8 Schaltfläche F8 Stat: zeigt die Statistik der Anfragen an diesen Endpunkt.

Eingabemaske

 ↩ Enter öffnet die Eingabemaske REST-Endpunkt. Ein neuer Endpunkt ist als Aktiv vorbelegt.

Feld Bedeutung
Pfad-Template Vollständiger Pfad nach Host und Port, mit Platzhaltern, z.B. /orders/{uid}/modules/{code}. Maßgeblich für die Zuordnung der Anfragen, siehe Routing über Pfad-Templates. Pflichtfeld.
Server Server-Profil, auf dem der Endpunkt erreichbar ist. Auf anderen Profilen antwortet der Server für diesen Pfad mit 404. Pflichtfeld.
zusätzliche Infos Freitext zur Dokumentation. Wird nicht ausgewertet.
Datei-Upload Der Endpunkt nimmt Dateien an. Ohne Haken weist der Server Uploads mit 415 ab, das Skript läuft dann nicht.
maximale Dateigröße (MB) Obergrenze für Uploads in MB. Leer oder 0 bedeutet 25 MB. Darüber antwortet der Server mit 413.
Aktiv Nur aktive Endpunkte sind erreichbar. Ein inaktiver Endpunkt antwortet mit 404.

Das Skript des Endpunkts bearbeiten Sie in der Liste mit F7.

Routing über Pfad-Templates

Der Server ordnet jede Anfrage über das Pfad-Template einem Endpunkt zu:

  • Statische Segmente müssen übereinstimmen. Groß- und Kleinschreibung spielt keine Rolle.
  • Platzhalter in geschweiften Klammern, z.B. {uid}, passen auf jeden Wert. Der Wert steht dem Skript als Pfad-Parameter zur Verfügung.
  • Die Zahl der Segmente muss gleich sein. /orders passt nicht auf /orders/{uid}.
Template Passt auf Pfad-Parameter
/orders /orders –
/orders/{uid} /orders/4711 uid = 4711
/orders/{uid}/modules/{code} /orders/4711/modules/A1 uid = 4711, code = A1
/kalender/v1 /kalender/v1 –

Passen mehrere Templates, gewinnt das spezifischste, also das mit den meisten statischen Segmenten. So schlägt /orders/summary das Template /orders/{uid}, während /orders/4711 auf /orders/{uid} passt. Haben zwei Templates gleich viele statische Segmente, ist nicht festgelegt, welches gewinnt. Vermeiden Sie solche Überschneidungen.

Passt kein Template, antwortet der Server mit 404 NOT_FOUND. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt HTTP-Schnittstelle.

Pfad-Parameter im Skript

Das Skript liest die Werte der Platzhalter über oReader.Path:

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
    cUid := oReader.Path('uid');   // aus /orders/{uid}
end;

Der Name des Parameters ist geschützt: Query-Parameter oder Header können ihn nicht überschreiben. Der Wert kommt aber aus der Adresse, die der Client sendet. Prüfen Sie ihn im Skript wie jede andere Eingabe. Details: Scripting.

URL-Struktur

https://<Host>[:<Port>]<Pfad-Template>

Beispiele:

HTTP-Methode

Der Server ruft im Skript die Methode auf, die zum HTTP-Verb passt: Get, Post, Put, Patch oder Delete. Fehlt die Methode im Skript, antwortet er mit 405 und nennt im Header Allow die vorhandenen.

Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie /orders und /orders/{uid} sind eigene Endpunkte mit eigenem Skript und eigener Berechtigung.

Schreibende Aufrufe (POST, PUT, PATCH, DELETE) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header Idempotency-Key, am Endpunkt ist nichts einzustellen. Details: HTTP-Schnittstelle.

Versionierung

Die Version eines Endpunkts nehmen Sie als statisches Segment ins Template auf, z.B. /orders/v1 oder /v1/orders/{uid}. Eine Änderung ohne Bruch für bestehende Clients:

  1. Lassen Sie den bestehenden Endpunkt unverändert.
  2. Legen Sie einen neuen Endpunkt mit neuem Versions-Segment an.
  3. Vergeben Sie die Berechtigungen für die Clients, die umstellen.
  4. Deaktivieren Sie den alten Endpunkt, wenn alle Clients umgestellt sind.

Zugriffskontrolle

Ein Zugang darf einen Endpunkt nur nutzen, wenn er dafür berechtigt ist. Die Berechtigungen stehen in der Tabelle RESTSRV_ACCESS.

So vergeben Sie eine Berechtigung:

  1. Markieren Sie den Endpunkt in der Liste und drücken Sie F6. Die Liste Endpunkt Zugang zeigt die berechtigten Zugänge.
  2. Drücken Sie Einfg. Die Liste der Zugänge öffnet sich zur Auswahl.
  3. Markieren Sie die gewünschten Zugänge mit F5 und übernehmen Sie sie mit F2.
ACHTUNG: Ein Endpunkt ohne Berechtigung sieht fertig aus: Pfad, Skript und Server-Profil stimmen, der Aufruf scheitert trotzdem mit 403 FORBIDDEN_ROLE und der Meldung „Zugriff verweigert“. Im Protokoll steht „Keine Berechtigung fuer die Endpunkt-Nutzung“. Vergeben Sie deshalb beim Anlegen immer auch die Berechtigung, und prüfen Sie bei einem 403 zuerst, ob sie existiert.

Weil jede Pfad-Form ein eigener Endpunkt ist, vergeben Sie die Rechte je Pfad-Form. So erlauben Sie z.B. das Lesen von /orders/{uid}, aber nicht das Ändern über /orders/{uid}/modules/{code}.

Dateien

  • Upload: Mit Datei-Upload nimmt der Endpunkt Dateien an, bis zur maximalen Dateigröße (MB). Übertragungsarten, Header und Statuscodes beschreibt Datei-Upload.
  • Download: Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe Datei-Download.

Caching

Der Server hält die Endpunkte eines Server-Profils samt Skript 60 Sekunden im Speicher. Neue oder geänderte Endpunkte, Templates und Skripte wirken deshalb spätestens nach 60 Sekunden. Nach einem Neustart des REST-Dienstes wirken sie sofort.

WebHooks

Ein WebHook ist ein Endpunkt für einen einmaligen Rückruf. Typischer Einsatz: OBS stößt einen Vorgang bei einem Fremdsystem an, z.B. einem Bezahldienst oder Versanddienstleister, und gibt ihm eine Rückruf-Adresse mit, die nur einmal gilt. Die Adresse lässt sich danach nicht erneut oder von anderen benutzen.

Ablauf:

  1. OBS legt einen Eintrag in der Tabelle REMOTE_HOOK_URL an und dazu einen Endpunkt, der auf diesen Eintrag verweist. Ein Skript hat dieser Endpunkt nicht.
  2. Die Adresse dieses Endpunkts erhält das Fremdsystem als Rückruf-Adresse.
  3. Das Fremdsystem ruft die Adresse auf. Der Server speichert den empfangenen Inhalt in REMOTE_HOOK_URL.hu_response, antwortet mit {"status": "ok"} und löscht den Endpunkt.
  4. Der weiterverarbeitende OBS-Vorgang liest die Rückmeldung aus hu_response.

Für den Aufruf gilt:

  • Wie bei jedem Endpunkt prüft der Server API-Key und Berechtigung des Zugangs.
  • Ein Idempotency-Key ist nicht nötig.
  • Ein zweiter Aufruf derselben Adresse erhält sofort 404. Das ist gewollt: Ein WebHook ist keine dauerhafte Schnittstelle. Für eine dauerhafte Rückmelde-Adresse legen Sie einen normalen Endpunkt mit Skript an.
  • Fehlt der Eintrag in REMOTE_HOOK_URL, antwortet der Server mit 500.

Siehe auch