Version vom 15. Juni 2026, 08:04 Uhr

Ein Endpunkt stellt eine Adresse bereit, über die der REST-Server konkrete Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook realisiert und ist genau einem Server-Profil zugeordnet.

Routing über Pfad-Templates

Das Routing erfolgt über die Spalte Pfad-Template (re_pathtemplate). Ein Template beschreibt den vollständigen Pfad nach dem Host und kann Platzhalter enthalten:

Statische Segmente müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
Platzhalter in geschweiften Klammern – z. B. {uid} – passen auf einen beliebigen Wert und werden als Pfad-Parameter erfasst.

Beispiele für gültige Templates:

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`	–

Präzedenz bei mehreren Treffern

Passen mehrere Templates auf denselben Pfad, 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} matcht.

Hauptfelder eines Endpunkts

Feld	Spalte	Zweck
Endpunkt	`re_endpoint`	Ressourcen-/Anzeigename (z. B. `orders`). Hinweis: wird seit Umstellung auf Pfad-Templates nicht mehr für das Routing ausgewertet, dient nur noch der Übersicht/Gruppierung. Sinnvoll: erstes statisches Segment des Templates eintragen.
Pfad-Template	`re_pathtemplate`	Maßgeblich fürs Routing. Vollständiger Pfad mit Platzhaltern, z. B. `/orders/{uid}/modules/{code}`
Server	`re_server`	Zuordnung zum Server-Profil (erforderlich)
Aktiv	`re_aktiv`	Statusflag; inaktive Endpunkte liefern 404
Skript	`re_script`	DwScript-Quelltext des Handlers (siehe Scripting)
WebHook	`re_webhook`	optional: Verweis auf einen Einmal-Endpunkt statt Skript
Info	–	Dokumentations-Freitext

HINWEIS: Die früheren Felder Sub-URL (re_suburl) und

Version (re_version) werden vom Routing nicht mehr ausgewertet. Die Version wird – falls benötigt – als statisches Segment Teil

des Pfad-Templates (siehe Versionierung).

Pfad-Parameter im Skript

Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als reservierte Parameter mit Präfix _OBS_PATH_ zur Verfügung:

function Get(oParams: TStrings; oBody: TJSONObject): string;
var cUid: string;
begin
    cUid := oParams.Values['_OBS_PATH_uid'];   // aus /orders/{uid}
    // ...
end;

Da der Präfix _OBS_ für von außen gelieferte Header/Query-Parameter gesperrt ist, können diese Werte nicht durch den Client überschrieben werden.

HTTP-Methode

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft die gleichnamige Skript-Methode auf (Get/Post/Put/Delete/Patch). Ein Template entspricht damit einem Endpunkt-Skript; unterschiedliche Pfad-Formen (z. B. /orders vs. /orders/{uid}) sind eigene Endpunkt-Einträge mit eigenem Skript und eigener Berechtigung.

URL-Struktur

http://[Host][:Port][Pfad-Template]

Beispiele:

Versionierung

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches Segment ins Template aufgenommen, z. B. /orders/v1 oder /v1/orders/{uid}. Änderung ohne Breaking Change:

Bestehenden Endpunkt unverändert lassen.
Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
Berechtigungen für neue Konsumenten setzen.
Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

Zugriffskontrolle

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite Berechtigung (Tabelle RESTSRV_ACCESS), um einen Endpunkt nutzen zu dürfen. Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der Zugriff pro Pfad-Form granular vergeben (z. B. Lesen von /orders/{uid} erlauben, aber das ändernde PUT /orders/{uid}/modules/{code} nicht).

Caching

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert (TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht zwingend sofort.

HTTP-Fehlercodes

Code	Ursache
404	Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
403	Zugang fehlt in der Berechtigungsliste
401	API-Key ungültig/fehlend oder JWT abgelaufen
500	Skript- oder Syntax-Fehler (Details in `RESTSRV_PROTO`)

WebHooks

WebHooks sind Einmal-Endpunkte für asynchrone Callbacks. Beim ersten erfolgreichen Aufruf wird die Antwort in der Tabelle REMOTE_HOOK_URL gespeichert und der Endpunkt anschließend automatisch gelöscht.

Siehe auch

@@ Zeile 1: / Zeile 1: @@
 {{Kostenpflichtige Module}}
+= Endpunkte =
-=Endpunkte=
+Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
+Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
+realisiert und ist genau einem Server-Profil zugeordnet.
-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).
+== Routing über Pfad-Templates ==
-==Aufruf==
+Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
+Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
+'''Platzhalter''' enthalten:
-'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Endpunkte'''
+* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
+* '''Platzhalter''' in geschweiften Klammern – z.&nbsp;B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.
-==Felder==
+Beispiele für gültige Templates:
 {| class="wikitable"
-! Feld     !! Beschreibung
+! Template !! Passt auf !! Pfad-Parameter
 |-
-| Endpunkt || Hauptname, erster Pfad-Bestandteil nach der Hostadresse (Pflichtfeld)
+| <code>/orders</code> || <code>/orders</code> || –
 |-
-| Sub-URL  || Optionaler zweiter Pfad-Bestandteil, z.B. ''mobile'', ''office''
+| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
 |-
-| Version  || Versionsbezeichner, z.B. ''v1'', ''v1.0'', ''v2''
+| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
 |-
-| Server   || Zuordnung zu einem Server-Profil. Der Endpunkt ist nur über dieses Profil erreichbar (Pflichtfeld)
+| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
-|-
-| Aktiv    || Inaktive Endpunkte sind nicht ansprechbar (404)
-|-
-| Info     || Freitext zur Dokumentation
 |}
-==Adressbildung==
+=== Präzedenz bei mehreren Treffern ===
-Die Adresse setzt sich aus Endpunkt, Sub-URL und Version zusammen:
+Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
+also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
+das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
+<code>/orders/{uid}</code> matcht.
- http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]
+== Hauptfelder eines Endpunkts ==
-Beispiele:
+{| class="wikitable"
+! Feld !! Spalte !! Zweck
+|-
+| '''Endpunkt''' || <code>re_endpoint</code> || Ressourcen-/Anzeigename (z.&nbsp;B. <code>orders</code>). '''Hinweis:''' wird seit Umstellung auf Pfad-Templates '''nicht mehr für das Routing''' ausgewertet, dient nur noch der Übersicht/Gruppierung. Sinnvoll: erstes statisches Segment des Templates eintragen.
+|-
+| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z.&nbsp;B. <code>/orders/{uid}/modules/{code}</code>
+|-
+| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
+|-
+| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
+|-
+| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
+|-
+| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
+|-
+| '''Info''' || – || Dokumentations-Freitext
+|}
- https://api.meinserver.de/kalender/v1
+{{Hinweis|Die früheren Felder '''Sub-URL''' (<code>re_suburl</code>) und
- https://api.meinserver.de/email/mein_konto/v1.0
+'''Version''' (<code>re_version</code>) werden vom Routing '''nicht mehr
+ausgewertet'''. Die Version wird – falls benötigt – als statisches Segment Teil
+des Pfad-Templates (siehe [[#Versionierung|Versionierung]]).}}
-Wird die Sub-URL leer gelassen, verkürzt sich die Adresse auf ''/Endpunkt/Version''.
+== Pfad-Parameter im Skript ==
-==Versionierung==
+Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
+reservierte Parameter mit Präfix <code>_OBS_PATH_</code> zur Verfügung:
-Die Versionierung erlaubt es, eine Endpunkt-Funktionalität zu ändern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
+<syntaxhighlight lang="pascal">
+function Get(oParams: TStrings; oBody: TJSONObject): string;
+var cUid: string;
+begin
+    cUid := oParams.Values['_OBS_PATH_uid'];   // aus /orders/{uid}
+    // ...
+end;
+</syntaxhighlight>
-# Den vorhandenen Endpunkt unverändert lassen, weiterhin aktiv halten.
+Da der Präfix <code>_OBS_</code> für von außen gelieferte Header/Query-Parameter
-# Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen.
+gesperrt ist, können diese Werte nicht durch den Client überschrieben werden.
-# Berechtigungen für die neuen Konsumenten setzen.
-# Wenn alle Konsumenten umgestellt sind, den alten Endpunkt deaktivieren.
-==Zuordnung zum Server-Profil==
+== HTTP-Methode ==
-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.
+Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
+die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
+Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
+Pfad-Formen (z.&nbsp;B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
+'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.
-==Berechtigungen==
+== URL-Struktur ==
-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.
+<pre>
+http://[Host][:Port][Pfad-Template]
+</pre>
-In der Berechtigungs-Liste:
+Beispiele:
+* <code>https://api.meinserver.de/orders</code>
-* '''Einfg''' - öffnet die Zugänge-Liste.
+* <code>https://api.meinserver.de/orders/4711</code>
-* In der Zugänge-Liste mit '''F5''' einen oder mehrere Zugänge markieren.
+* <code>https://api.meinserver.de/orders/4711/modules/A1</code>
-* '''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:
+== Versionierung ==
-# Die übergebenen Daten (Query-String oder Request-Body) werden in der Tabelle '''REMOTE_HOOK_URL''' im Feld ''hu_response'' gespeichert.
+Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
-# Der Endpunkt wird automatisch aus '''RESTSRV_ENDPOINTS''' gelöscht.
+Segment ins Template aufgenommen, z.&nbsp;B. <code>/orders/v1</code> oder
-# Der Server antwortet mit ''{"status": "ok"}''.
+<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:
-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.
+# Bestehenden Endpunkt unverändert lassen.
+# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
+# Berechtigungen für neue Konsumenten setzen.
+# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.
-==Listen-Funktionen==
+== Zugriffskontrolle ==
-In der Endpunkt-Liste:
+Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
+Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
+dürfen. Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
+Zugriff '''pro Pfad-Form''' granular vergeben (z.&nbsp;B. Lesen von
+<code>/orders/{uid}</code> erlauben, aber das ändernde
+<code>PUT /orders/{uid}/modules/{code}</code> nicht).
-* '''Einfg''' - neuer Endpunkt
+== Caching ==
-* '''Return''' - Endpunkt bearbeiten
-* '''F4''' - Sortierung
-* '''F6''' - Berechtigungen verwalten (Zugänge dem Endpunkt zuordnen)
-* '''F7''' - Endpunkt-Skript bearbeiten
-* '''F8''' - Statistik für den Endpunkt
-==Cache==
+Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
+(TTL, Standard 60&nbsp;s). Neue oder geänderte Endpunkte/Templates werden daher
+erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
+zwingend sofort.
-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.
+== HTTP-Fehlercodes ==
-==Typische Fehlermeldungen==
 {| class="wikitable"
-! Code  !! Bedeutung
+! Code !! Ursache
 |-
-| 404   || Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil
+| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
 |-
-| 403   || Keine Berechtigung für die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste)
+| '''403''' || Zugang fehlt in der Berechtigungsliste
 |-
-| 401   || API-Key fehlt, ungültig, JWT fehlt oder ist abgelaufen
+| '''401''' || API-Key ungültig/fehlend oder JWT abgelaufen
 |-
-| 500   || Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO
+| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
 |}
+== WebHooks ==
+WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
+erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
+gespeichert und der Endpunkt anschließend automatisch gelöscht.
+== Siehe auch ==
+* [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]]
+* [[/OBS/Kostenpflichtige_Module/RESTServer/Beispiel4|Beispiel 4 – Pfad-Parameter]]

OBS/Kostenpflichtige Module/RESTServer/Endpunkte: Unterschied zwischen den Versionen

Version vom 15. Juni 2026, 08:04 Uhr

Inhaltsverzeichnis

Endpunkte

Routing über Pfad-Templates

Präzedenz bei mehreren Treffern

Hauptfelder eines Endpunkts

Pfad-Parameter im Skript

HTTP-Methode

URL-Struktur

Versionierung

Zugriffskontrolle

Caching

HTTP-Fehlercodes

WebHooks

Siehe auch

Navigationsmenü

OBS/Kostenpflichtige Module/RESTServer/Endpunkte: Unterschied zwischen den Versionen

Version vom 15. Juni 2026, 08:04 Uhr

Endpunkte

Routing über Pfad-Templates

Präzedenz bei mehreren Treffern

Hauptfelder eines Endpunkts

Pfad-Parameter im Skript

HTTP-Methode

URL-Struktur

Versionierung

Zugriffskontrolle

Caching

HTTP-Fehlercodes

WebHooks

Siehe auch

Navigationsmenü

Suche