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

Aus OBS Wiki
Zur Navigation springen Zur Suche springen
(Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} =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-Best…“)
Keine Bearbeitungszusammenfassung
 
(6 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Kostenpflichtige Module}}


=Endpunkte=
= 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).
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.


==Aufruf==
== Routing über Pfad-Templates ==


'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Endpunkte'''
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:


==Felder==
* '''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.
 
Beispiele für gültige Templates:


{| class="wikitable"
{| class="wikitable"
! Feld    !! Beschreibung
! Template !! Passt auf !! Pfad-Parameter
|-
| 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''
| <code>/orders</code> || <code>/orders</code> || –
|-
|-
| Server  || Zuordnung zu einem Server-Profil. Der Endpunkt ist nur ueber dieses Profil erreichbar (Pflichtfeld)
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
|-
| Aktiv    || Inaktive Endpunkte sind nicht ansprechbar (404)
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
|-
| Info    || Freitext zur Dokumentation
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}
|}


==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
|-
| '''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
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25&nbsp;MB. Überschreitung wird mit 413 abgelehnt.
|}


https://api.meinserver.de/kalender/v1
== Pfad-Parameter im Skript ==
https://api.meinserver.de/email/mein_konto/v1.0


Wird die Sub-URL leer gelassen, verkuerzt sich die Adresse auf ''/Endpunkt/Version''.
Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
reservierte Parameter mit Präfix <code>_OBS_PATH_</code> zur Verfügung:


==Versionierung==
<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>


Die Versionierung erlaubt es, eine Endpunkt-Funktionalitaet zu aendern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
Da der Präfix <code>_OBS_</code> für von außen gelieferte Header/Query-Parameter
gesperrt ist, können diese Werte nicht durch den Client überschrieben werden.


# Den vorhandenen Endpunkt unveraendert lassen, weiterhin aktiv halten.
== Datei-Uploads ==
# 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 nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.


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.
Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25&nbsp;MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10&nbsp;MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Dem Skript stehen Pfad, Name und Content-Type als <code>_OBS_UPLOAD_*</code>-Parameter zur Verfügung (Details: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).


==Berechtigungen==
Unterstützt werden zwei Übertragungsarten:


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.
* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).


In der Berechtigungs-Liste:
Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].


* '''Einfg''' - oeffnet die Zugaenge-Liste.
== HTTP-Methode ==
* 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.
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.


==Endpunkt-Skript==
== URL-Struktur ==


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.
<pre>
http://[Host][:Port][Pfad-Template]
</pre>


Die genaue Skript-Syntax und alle verfuegbaren Parameter sind unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] beschrieben.
Beispiele:
 
* <code>https://api.meinserver.de/orders</code>
==WebHooks==
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>


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:
== Versionierung ==


# Die uebergebenen 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''' geloescht.
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 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.
# 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 (Zugaenge dem Endpunkt zuordnen)
* '''F7''' - Endpunkt-Skript bearbeiten
* '''F8''' - Statistik fuer 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 ueber F7 geaendert, ist die neue Version sofort wirksam - der Server erkennt die Aenderung am ''sys_date'' und compiliert neu.
== HTTP-Fehlercodes ==
 
==Typische Fehlermeldungen==


{| class="wikitable"
{| 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 fuer die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste)
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
|-
| 401   || API-Key fehlt, ungueltig, 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>)
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>)
|-
| '''429''' || Rate-Limit Überschritten; die Antwort enthÄlt den Header <code>Retry-After</code>
|}
|}
Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
== 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.

Aktuelle Version vom 30. Juni 2026, 12:29 Uhr

Kostenpflichtige Module

Internet-Shop
UPS
IMS Professional
SMS
Mehrlager-Verwaltung
Mehrsprachen Modul
Multilanguage Modul
EVA Marketing Tool
Termin-Projekte
Edifact-Schnittstelle
Backup Überwachung Email
OBS Geo Daten
DeliSprint / DPD
Filialen
Cashback
Moebelschnittstelle
Dokumenten Manager
DocuWare-Schnittstelle
OFML-Kalkulation
Versicherungsschaden
Gutschriftsanzeigen
Kameraverwaltung
DataInOut
OpenMasterData / IDS
Sammelpositionen


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.

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
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
Datei-Upload re_upload Erlaubt Datei-Uploads an diesem Endpunkt (0 = aus, 1 = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
Max. Upload-Grösse re_upload_size Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.

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.

Datei-Uploads

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist (re_upload = 1). Andernfalls werden Upload-Anfragen mit 415 Unsupported Media Type abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über re_upload_size (in MB) festgelegt; ohne Angabe gilt der Standard von 25 MB. Wird das Limit überschritten, antwortet der Server mit 413 Payload Too Large. Für Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit. Der Originalname (beim resumable Upload über den Header Upload-Metadata) ist Pflicht; fehlt er, wird der Upload mit 413/400 abgelehnt. Dem Skript stehen Pfad, Name und Content-Type als _OBS_UPLOAD_*-Parameter zur Verfügung (Details: Scripting).

Unterstützt werden zwei Übertragungsarten:

  • Einfacher Upload per multipart/form-data (eine Datei pro Request).
  • Resumable/Chunked Upload per Content-Range (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage, DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und Beispiele: Scripting.

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:

  1. Bestehenden Endpunkt unverändert lassen.
  2. Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
  3. Berechtigungen für neue Konsumenten setzen.
  4. 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)
415 Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (re_upload = 0)
413 Hochgeladene Datei überschreitet die zulässige Maximalgrösse (re_upload_size)
429 Rate-Limit Überschritten; die Antwort enthÄlt den Header Retry-After

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. 201, 204, 409, 422) sowie Response-Header wie ETag oder Location - siehe Scripting.

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.