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
 
(9 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''' 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''' (<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).
* '''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"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <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> || –
|}
 
=== Präzedenz bei mehreren Treffern ===
 
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"
! 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.
|}
 
== Pfad-Parameter im Skript ==
 
Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
reservierte Parameter mit Präfix <code>_OBS_PATH_</code> zur Verfügung:
 
<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>
 
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.
 
== Datei-Uploads ==
 
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.
 
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]]).
 
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]].
 
== HTTP-Methode ==
 
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.
 
== URL-Struktur ==
 
<pre>
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 ==
 
Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z.&nbsp;B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Ä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 <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).
 
== Caching ==
 
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>)
|-
| '''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>
|-
| '''503''' || Eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet; die Antwort enthält <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''' || Die Anfrage wurde unverschlüsselt an einen TLS-Port geschickt (<code>http</code> statt <code>https</code>). Die Abweisung erfolgt vor Authentifizierung und Endpunkt-Skript
|}
 
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 ==
 
Schickt ein Konsument bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code>
oder <code>DELETE</code> den Header <code>Idempotency-Key</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.
 
{| class="wikitable"
! Situation !! Antwort des Servers
|-
| 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>. Der Dienst wurde zwischen Verarbeitung und Festschreiben unterbrochen; ob die Buchung stattgefunden hat, ist unbekannt und von Hand zu klären
|}
 
Wichtig für die Auslegung eines Endpunkts:
 
* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* 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, bleibt der Schlüssel belegt und der Fall wird protokolliert. Das ist Absicht: lieber ein Fall für den Support als eine mögliche Doppelbuchung.
 
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> und werden nach 30 Tagen
automatisch aufgeräumt. Einträge ohne Ergebnis werden '''nicht''' automatisch
gelöscht, sondern im Protokoll gemeldet.
 
== 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.
 
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:
 
# 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.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# 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'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.
 
{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

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