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

Aus OBS Wiki
Zur Navigation springen Zur Suche springen
Keine Bearbeitungszusammenfassung
Keine Bearbeitungszusammenfassung
Zeile 53: Zeile 53:
|-
|-
| '''Info''' || – || Dokumentations-Freitext
| '''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.
|}
|}


Zeile 71: Zeile 75:
Da der Präfix <code>_OBS_</code> für von außen gelieferte Header/Query-Parameter
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.
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.
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 ==
== HTTP-Methode ==
Zeile 130: Zeile 155:
|-
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
| '''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>
| '''429''' || Rate-Limit Überschritten; die Antwort enthÄlt den Header <code>Retry-After</code>

Version vom 30. Juni 2026, 11:51 Uhr

Kostenpflichtige Module

Internet-Shop
Der modified ECommerce Shop
Shop-Menü
Automatische Vorgänge
modified eCommerce 2.0
Der Büroring-ShopV4
Einrichtung
Eigene Artikel
brShop24
Einstellungen und Automatiken
Funktionen
Preislisten
Preislistenverwaltung
F10 Weitere Funktionen
Automatiken Kommandos
ZUGFeRD
Factoring
UPS
DHL
IMS Professional
TAPI
SMS
Fleet Management
Mehrlager-Verwaltung
Mehrsprachen Modul
Multilanguage Modul
Einfache Produktionsnachverfolgung
DMS - Dokumenten Management System
DMS Dokumente
Tasten und Schaltflächen
F10 Weit.
E DMS Definitionen
QR Zeiterfassung
EVA Marketing Tool
Technikersteuerung
Termin-Projekte
Edifact-Schnittstelle
Backup Überwachung Email
Anlagenbuchhaltung
OBS Geo Daten
DeliSprint / DPD
Filialen
Auto-Waagen
Cashback
Moebelschnittstelle
Tourenplanung
Tourenplanung
Dokumenten Manager
DocuWare-Schnittstelle
OFML-Kalkulation
Pascom
Versicherungsschaden
Gutschriftsanzeigen
OCPP Ladestationen
Kameraverwaltung
DataInOut
REST-Schnittstelle
Beispiele
Sammelverträge
Craftboxx
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.

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.

Abgerufen von „http:///index.php?title=OBS/Kostenpflichtige_Module/RESTServer/Endpunkte&oldid=64543“