Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Vorlage:-Praefix; Link ohne fuehrenden Schraegstrich korrigiert [Volltext ersetzt]
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]
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
 
{{Seitentyp|Maske}}
= Endpunkte =
= Endpunkte =


Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
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'''.
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''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:


* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
== Liste ==
* '''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.
Die Liste zeigt alle Endpunkte mit '''Pfad''' (dem Pfad-Template) und '''Serv''' (der Nummer des Server-Profils). Aktive Endpunkte erscheinen fett.
 
Beispiele für gültige Templates:


== Tasten und Schaltflächen ==
{| class="wikitable"
{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
! Taste !! Funktion
|-
| {{Einfg}} || Legt einen neuen Endpunkt an.
|-
| {{Return}} || Öffnet den markierten Endpunkt in der Eingabemaske.
|-
|-
| <code>/orders</code> || <code>/orders</code> || –
| {{F4}} || Wählt die Sortierung.
|-
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
| {{F6}} || Schaltfläche '''F6 Zugang''': öffnet die Liste der Zugänge, die diesen Endpunkt nutzen dürfen, siehe [[#Zugriffskontrolle|Zugriffskontrolle]].
|-
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
| {{F7}} || Schaltfläche '''F7 Script''': öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
|-
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
| {{F8}} || Schaltfläche '''F8 Stat''': zeigt die Statistik der Anfragen an diesen Endpunkt.
|}
|}


=== Präzedenz bei mehreren Treffern ===
== Eingabemaske ==
 
{{Return}} öffnet die Eingabemaske '''REST-Endpunkt'''. Ein neuer Endpunkt ist als '''Aktiv''' vorbelegt.
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.
 
== Hauptfelder eines Endpunkts ==


{| class="wikitable"
{| class="wikitable"
! Feld !! Spalte !! Zweck
! Feld !! Bedeutung
|-
|-
| '''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>
| '''Pfad-Template''' || Vollständiger Pfad nach Host und Port, mit Platzhaltern, z.B. <code>/orders/{uid}/modules/{code}</code>. Maßgeblich für die Zuordnung der Anfragen, siehe [[#Routing über Pfad-Templates|Routing über Pfad-Templates]]. Pflichtfeld.
|-
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
| '''Server''' || Server-Profil, auf dem der Endpunkt erreichbar ist. Auf anderen Profilen antwortet der Server für diesen Pfad mit '''404'''. Pflichtfeld.
|-
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
| '''zusätzliche Infos''' || Freitext zur Dokumentation. Wird nicht ausgewertet.
|-
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
| '''Datei-Upload''' || Der Endpunkt nimmt Dateien an. Ohne Haken weist der Server Uploads mit '''415''' ab, das Skript läuft dann nicht.
|-
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
| '''maximale Dateigröße (MB)''' || Obergrenze für Uploads in MB. Leer oder ''0'' bedeutet 25 MB. Darüber antwortet der Server mit '''413'''.
|-
|-
| '''Info''' || – || Dokumentations-Freitext
| '''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. <code>{uid}</code>, passen auf jeden Wert. Der Wert steht dem Skript als Pfad-Parameter zur Verfügung.
* '''Die Zahl der Segmente''' muss gleich sein. <code>/orders</code> passt nicht auf <code>/orders/{uid}</code>.
 
{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
|-
| '''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.
| <code>/orders</code> || <code>/orders</code> || –
|-
|-
| '''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.
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}
|}


== Pfad-Parameter im Skript ==
Passen mehrere Templates, 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> passt. Haben zwei Templates gleich viele statische Segmente, ist nicht festgelegt, welches gewinnt. Vermeiden Sie solche Überschneidungen.


Die aus den Platzhaltern erfassten Werte liest das Endpunkt-Skript über
Passt kein Template, antwortet der Server mit '''404''' <code>NOT_FOUND</code>. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Adressierung|HTTP-Schnittstelle]].
<code>oReader.Path</code>:


<syntaxhighlight lang="pascal">
=== Pfad-Parameter im Skript ===
Das Skript liest die Werte der Platzhalter über <code>oReader.Path</code>:
 
<syntaxhighlight lang="delphi">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
var cUid: string;
begin
begin
     cUid := oReader.Path('uid');  // aus /orders/{uid}
     cUid := oReader.Path('uid');  // aus /orders/{uid}
    // ...
end;
end;
</syntaxhighlight>
</syntaxhighlight>


Diese Werte stammen aus dem Routing und können nicht durch den Client
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: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
überschrieben werden.


== Datei-Uploads ==
=== URL-Struktur ===
<syntaxhighlight lang="text">
https://<Host>[:<Port>]<Pfad-Template>
</syntaxhighlight>


Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
Beispiele:
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
* <code>https://obs.example.com/orders</code>
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.
* <code>https://obs.example.com/orders/4711</code>
 
* <code>https://obs.example.com/orders/4711/modules/A1</code>
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 '''400''' abgelehnt, ohne dass eine Datei angelegt wird. Das Skript liest Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>; bei <code>multipart/form-data</code> die übrigen Formularfelder über <code>oReader.Form('&lt;name&gt;')</code>.
 
'''Das Übertragungsprotokoll''' - Header, Statuscodes, Resume-Verhalten - steht auf einer eigenen Seite: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].
 
Unterstützt werden zwei Übertragungsarten:
 
* '''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).
 
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]].
 
== Datei-Downloads ==
 
Ein Endpunkt kann eine '''Datei''' statt eines JSON-Körpers zurückgeben -
PDF, CSV, eine APK. Dafür ist '''keine Freischaltung''' nötig: ein Download
entsteht dadurch, dass das Skript ihn mit <code>oWriter.SendFile(...)</code>
bzw. <code>oWriter.SendTempFile(...)</code> erzeugt, nicht dadurch, dass ein
Client ihn anfragt.
 
Content-Type, Dateiname, Bereichsanfragen (<code>Range</code>, '''206'''),
ETag und das Aufräumen temporärer Dateien übernimmt der Server. Einzelheiten:
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].


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


Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie <code>/orders</code> und <code>/orders/{uid}</code> sind eigene Endpunkte mit eigenem Skript und eigener Berechtigung.
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.
 
== URL-Struktur ==


<pre>
Schreibende Aufrufe (<code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header <code>Idempotency-Key</code>, am Endpunkt ist nichts einzustellen. Details: [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].
http://[Host][:Port][Pfad-Template]
</pre>
 
Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>


== Versionierung ==
== Versionierung ==
Die Version eines Endpunkts nehmen Sie als statisches Segment ins Template auf, z.B. <code>/orders/v1</code> oder <code>/v1/orders/{uid}</code>. Eine Änderung ohne Bruch für bestehende Clients:
# Lassen Sie den bestehenden Endpunkt unverändert.
# Legen Sie einen neuen Endpunkt mit neuem Versions-Segment an.
# Vergeben Sie die Berechtigungen für die Clients, die umstellen.
# Deaktivieren Sie den alten Endpunkt, wenn alle Clients umgestellt sind.


Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
== Zugriffskontrolle ==
Segment ins Template aufgenommen, z.&nbsp;B. <code>/orders/v1</code> oder
Ein Zugang darf einen Endpunkt nur nutzen, wenn er dafür berechtigt ist. Die Berechtigungen stehen in der Tabelle <code>RESTSRV_ACCESS</code>.
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:


# Bestehenden Endpunkt unverändert lassen.
So vergeben Sie eine Berechtigung:
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Markieren Sie den Endpunkt in der Liste und drücken Sie {{F6}}. Die Liste '''Endpunkt Zugang''' zeigt die berechtigten Zugänge.
# Berechtigungen für neue Konsumenten setzen.
# Drücken Sie {{Einfg}}. Die Liste der Zugänge öffnet sich zur Auswahl.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.
# Markieren Sie die gewünschten Zugänge mit {{F5}} und übernehmen Sie sie mit {{F2}}.


== Zugriffskontrolle ==
{{Achtung|Ein Endpunkt ohne Berechtigung sieht fertig aus: Pfad, Skript und Server-Profil stimmen, der Aufruf scheitert trotzdem mit '''403''' <code>FORBIDDEN_ROLE</code> 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.}}


Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Weil jede Pfad-Form ein eigener Endpunkt ist, vergeben Sie die Rechte je Pfad-Form. So erlauben Sie z.B. das Lesen von <code>/orders/{uid}</code>, aber nicht das Ändern über <code>/orders/{uid}/modules/{code}</code>.
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen.


{{Achtung|'''Ein Endpunkt besteht aus zwei Zeilen, und beide werden von Hand
== Dateien ==
gepflegt:''' der Eintrag in <code>RESTSRV_ENDPOINTS</code> und die Berechtigung
* '''Upload:''' Mit '''Datei-Upload''' nimmt der Endpunkt Dateien an, bis zur '''maximalen Dateigröße (MB)'''. Übertragungsarten, Header und Statuscodes beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].
in <code>RESTSRV_ACCESS</code>. Fehlt die zweite, antwortet der Endpunkt
* '''Download:''' Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].
'''403''' - und sieht dabei fertig aus: Pfad, Skript und Server-Profil stehen
korrekt da, der Aufruf kommt trotzdem nicht durch. Das ist die häufigste Ursache
für ein „der Endpunkt ist doch angelegt" und kostet jedes Mal eine
Fehlersuche, weil der Statuscode nach einem Rechteproblem des Konsumenten
aussieht und nicht nach einer fehlenden Konfigurationszeile.
 
Beim Anlegen also '''immer beide Zeilen''', und beim Prüfen eines
<code>403</code> zuerst nachsehen, ob die zweite existiert.}} 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).


== Caching ==
== 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.
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.
 
== HTTP-Fehlercodes ==
 
{| class="wikitable"
! 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, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''206''' || Teilantwort eines Datei-Downloads auf eine <code>Range</code>-Anfrage; die Antwort enthält <code>Content-Range</code>
|-
| '''416''' || Der angefragte <code>Range</code> liegt hinter dem Dateiende; die Antwort nennt in <code>Content-Range</code> die wirkliche Grösse
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>); oder ein <code>Content-Encoding</code>, das der Server nicht entpacken kann - unterstützt wird allein <code>gzip</code> (siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>); oder der Anfragekörper überschreitet 10 MB bzw. - gepackt gesendet - das 400fache der gesendeten Grösse
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Vier Ursachen, unterscheidbar am <code>code</code>: <code>IDEMPOTENCY_IN_PROGRESS</code> (eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet), <code>SERVICE_UNAVAILABLE</code> bei erreichter Andrangsgrenze des Server-Profils (<code>rsv_max_parallel</code>), bei einer Anmeldung, deren Sitzungszeile nicht geschrieben werden konnte, sowie bei einem fehlgeschlagenen <code>JwtRevoke</code>. Alle vier tragen <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Ein schreibender Aufruf (POST/PUT/PATCH/DELETE) '''ohne''' <code>Idempotency-Key</code> (<code>IDEMPOTENCY_KEY_MISSING</code>); ein resumable Upload ohne Dateinamen; oder eine Anfrage, die unverschlüsselt an einen TLS-Port geschickt wurde (<code>http</code> statt <code>https</code>) - letztere wird vor Authentifizierung und Endpunkt-Skript abgewiesen
|-
| '''308''' || Zwischenantwort beim resumable Upload: das Teilstück wurde angehängt, der Upload ist noch nicht vollständig. Die Antwort trägt <code>Upload-Id</code>, <code>Upload-Offset</code> und <code>Range</code>; das Skript läuft dabei '''nicht'''
|}
 
Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].
 
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]].
 
== Idempotenz ==
 
Bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code>
sorgt der Server selbst dafür, dass eine wiederholte Sendung '''keine
Zweitwirkung''' hat. Das gilt für '''jeden''' Endpunkt - es muss weder am Endpunkt
etwas eingestellt noch im Skript etwas programmiert werden.
 
{{Achtung|'''Der Header <code>Idempotency-Key</code> ist bei diesen vier Verben
Pflicht.''' Fehlt er, antwortet der Server mit '''400'''
<code>IDEMPOTENCY_KEY_MISSING</code> und das Endpunkt-Skript läuft '''nicht''' an.
 
Bis v1.21 lief eine Anfrage ohne den Header ungeschützt durch; der Schutz gegen
die Doppelbuchung lag damit beim Client. Ausgenommen ist allein der
JWT-Endpunkt (Anmelden, Erneuern, Abmelden) - er greift vor der Adressauflösung
und kennt die Mechanik nicht.}}
 
{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Kein <code>Idempotency-Key</code> gesendet || '''400''' <code>IDEMPOTENCY_KEY_MISSING</code>. Das Skript läuft nicht
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}
 
Wichtig für die Auslegung eines Endpunkts:
 
* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* '''Ausnahme Dateiantwort:''' Liefert das Skript mit <code>SendFile</code>/<code>SendTempFile</code> eine '''Datei''' aus, wird '''nichts''' festgeschrieben - eine Dateiantwort liesse sich nicht wiedergeben, gespeichert würde eine leere 200er-Antwort. Der Schlüssel wird stattdessen wieder freigegeben, ein erneuter Abruf derselben Datei ist unschädlich.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.
 
Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).
 
Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code>. Abgeschlossene Einträge
werden nach '''30 Tagen''' gelöscht. Einträge '''ohne Ergebnis''' - sie entstehen
nur bei einem harten Abbruch des Dienstes - werden ab '''24 Stunden''' im Protokoll
gemeldet und '''anschliessend ebenfalls gelöscht'''. Das Stehenlassen wäre keine
Vorsicht, sondern eine Sperre: derselbe Vorgang mit demselben Schlüssel wäre sonst
nie wieder durchführbar.


== WebHooks ==
== 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.
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.
 
Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.


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


# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
Für den Aufruf gilt:
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
* Wie bei jedem Endpunkt prüft der Server API-Key und Berechtigung des Zugangs.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
* Ein <code>Idempotency-Key</code> ist nicht nötig.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.
* 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 <code>REMOTE_HOOK_URL</code>, antwortet der Server mit '''500'''.


{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
== Siehe auch ==
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]
normalen Endpunkt mit Skript anlegen.}}
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

Version vom 17. November 2026, 06:59 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