|
|
| (8 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. 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. 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 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 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 <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit 413/400 abgelehnt. Dem Skript stehen Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei als <code>_OBS_UPLOAD_*</code>-Parameter zur Verfügung; bei <code>multipart/form-data</code> zusätzlich die übrigen Formularfelder als <code>_OBS_FORM_*</code> (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. 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. 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. 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 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
| |
| |-
| |
| | '''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>. 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.
| |
| * 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> 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.}}
| |