Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]
MINERVA-Rademacker (Diskussion | Beiträge)
Seitenliste: Pflege ersetzt Server-Profile, Zugänge und Endpunkte; Zugang gehört fest zu einem Server-Profil [Volltext ersetzt]
 
(3 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
=REST-Server=
{{Seitentyp|Übersicht}}
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}
= REST-Server =


==Was leistet der REST-Server?==
Der REST-Server ist die '''universelle Schnittstelle''' Ihrer OBS-Installation nach außen. Webseiten, Apps, Geräte, Kundensysteme und Cloud-Dienste lesen Daten direkt aus OBS oder liefern neue Daten direkt in OBS ab. Diese Seite zeigt, was der REST-Server leistet, und führt Administratoren und Entwickler zu den passenden Unterseiten.


Der REST-Server ist die '''universelle Schnittstelle''' Ihrer OBS-Installation nach außen. Er macht aus Ihrem OBS einen Dienst, mit dem andere Programme - Webseiten, Apps, Geräte, Kundensysteme, Cloud-Dienste - direkt sprechen können. Statt Daten manuell zu exportieren, zu mailen oder über Umwege bereitzustellen, holen sich angebundene Systeme genau die Information, die sie brauchen, in dem Moment, in dem sie sie brauchen - oder liefern neue Daten direkt in OBS ab.
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}
 
Für Anwender, die nicht selbst programmieren, bedeutet das: '''Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich jetzt automatisieren.''' Eine Webseite zeigt live aktuelle Lagerbestände. Mitarbeiter erfassen Zeiten über das Handy, ohne dass jemand Excel-Listen einpflegen muss. Ein Kunde stößt per Bestelltaste in seinem System einen Vorgang in Ihrem OBS an. Ein Lieferant meldet Wareneingänge automatisch zurück. Jeder dieser Anwendungsfälle wird einmal eingerichtet und läuft danach automatisch.
 
Technisch gesehen ist der REST-Server ein in OBS integrierter, voll konfigurierbarer '''HTTP/HTTPS-Dienst''', dessen Endpunkte über in OBS gepflegte Pascal-Skripte realisiert werden. Jeder Endpunkt bekommt eine eigene Adresse, eine eigene Logik und eine eigene Berechtigungsstruktur. Rückgaben erfolgen ausschliesslich im JSON-Format. Damit lassen sich beliebige Lese- und Schreibvorgänge auf der OBS-Datenbank realisieren, ohne dass externe Systeme direkten Datenbank-Zugriff erhalten - das ganze OBS-Regelwerk (Rechte, Validierung, Geschäftslogik) bleibt aktiv.
 
Im Ergebnis ist der REST-Server kein einzelnes Feature, sondern ein '''Werkzeugkasten''': Was an Daten oder Funktionen in OBS verfügbar ist, kann über den REST-Server auch nach außen angeboten - oder von außen entgegengenommen - werden. Die Bandbreite reicht vom einfachen Lese-Endpunkt für ein Webseiten-Widget bis hin zu kompletten B2B-Integrationen mit Mandanten- und Rollen-Trennung.
 
Aufruf des Moduls in OBS:
'''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''
 
==Anwendungsbereiche==
 
Die folgenden Einsatzfälle sind typische Beispiele, an denen sich der praktische Nutzen ablesen lässt. Es ist keine abschliessende Liste - alles, was sich in OBS-Skripten abbilden lässt, kann auch über einen Endpunkt bereitgestellt werden.
 
{{Hinweis|Dies sind Beispiele. Für die konkrete Entwicklung können, je nach Komplexität, weitere Kosten anfallen.}}
 
===Webseiten und Kundenportale===


* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise, Auftragsstatus aus OBS direkt anzeigen, ohne tägliche Datei-Exports.
Sie erreichen das Modul über '''Stammdaten → Z Weitere Stammdaten → REST-Server'''.
* '''Kundenportale:''' Kunden sehen ihre offenen Posten, Auftragshistorie, Lieferscheine. Die Seite holt sich die Daten zur Anzeigezeit direkt aus OBS, jeder Kunde sieht nur seine eigenen Daten.
* '''Trackingseiten:''' Status einer Bestellung, eines Auftrags oder einer Reparatur für Endkunden, abrufbar über eine Sendungsnummer.


===Mobile Anwendungen und Außendienst===
== Nutzen ==


* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
Statt Daten zu exportieren, per Mail zu verschicken und woanders wieder einzulesen, holen sich angebundene Systeme genau die Information, die sie brauchen – in dem Moment, in dem sie sie brauchen. '''Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich automatisieren.''' Jeder Anwendungsfall wird einmal eingerichtet und läuft danach von selbst.
* '''QR-/Barcode-Scanner und Lagergeräte:''' Wareneingang, Inventur, Kommissionierung direkt in OBS abbilden, ohne zwischengeschaltete Software.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material - synchronisiert mit OBS.


===Anbindung von Drittsystemen===
Technisch ist der REST-Server ein in OBS integrierter '''HTTPS-Dienst'''. Jeder Endpunkt hat eine eigene Adresse, ein eigenes Skript und eigene Berechtigungen. Die Skripte pflegen Sie direkt in OBS. Antworten liefert der Server als JSON oder als Datei. Externe Systeme erhalten keinen Zugriff auf die Datenbank. Sie sehen nur, was ein Endpunkt-Skript freigibt.


* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
Der REST-Server ist damit ein '''Werkzeugkasten''': Was an Daten oder Funktionen in OBS verfügbar ist, können Sie über einen Endpunkt nach außen anbieten oder von außen entgegennehmen. Die Bandbreite reicht vom einfachen Lese-Endpunkt für eine Webseite bis zur B2B-Anbindung mit getrennten Zugängen je Partner.
* '''Buchhaltungs- und ERP-Systeme:''' Bidirektionaler Austausch von Belegen, Stammdaten und Buchungen.
* '''CRM- und Marketing-Tools:''' Personendaten, Aktivitäten oder Mailing-Empfänger werden synchron gehalten.
* '''Logistikdienstleister:''' Versandaufträge werden übergeben, Tracking-Informationen zurückgeliefert.


===Automatisierte Rückmeldungen (WebHooks)===
=== Was Sie damit erreichen ===
* '''Manuelle Arbeit fällt weg.''' Daten fließen direkt, ohne Export, Mail und Import.
* '''Weniger Fehler.''' Jede manuelle Übertragung ist eine Fehlerquelle weniger.
* '''Neue Angebote werden möglich.''' Kunden- und Lieferantenportale, Self-Service und Apps greifen auf OBS zu, ohne dass Sie ein zweites System pflegen.
* '''Bestehende Software bleibt.''' Vorhandene Anwendungen docken über den REST-Server an OBS an, in beide Richtungen.
* '''Wächst mit.''' Ein einzelner Endpunkt für eine Webseite lässt sich zu einer kompletten Integrationsplattform ausbauen, ohne die Grundlage zu wechseln.


* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
=== Anwendungsbereiche ===
* '''Versanddienste:''' Statusmeldungen (verschickt, zugestellt, retour) werden direkt im passenden Vorgang dokumentiert.
Die folgenden Einsatzfälle sind Beispiele. Alles, was sich in einem Endpunkt-Skript abbilden lässt, kann der REST-Server bereitstellen.
* '''Cloud-Workflows:''' Externe Automatisierungs-Plattformen (Make, Zapier, n8n, ...) stoßen OBS-Vorgänge an oder werden von OBS aus angesprochen.


===Geschäftspartner-Kommunikation (B2B)===
{{Hinweis|Ob für Ihren Anwendungsfall Entwicklungsaufwand entsteht, klärt Ihr OBS-Betreuer mit Ihnen.}}


* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
==== Webseiten und Kundenportale ====
* '''Kunden-Schnittstelle:''' Grosskunden bestellen direkt aus ihrem ERP heraus, Stammdaten und Konditionen werden zentral gepflegt.
* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise oder Auftragsstatus direkt aus OBS, ohne tägliche Datei-Exporte.
* '''Sichere Maschine-zu-Maschine-Kommunikation:''' Mit Mutual-TLS (mTLS) wird sichergestellt, dass nur die freigeschalteten Partnersysteme - und niemand sonst - mit OBS sprechen können.
* '''Kundenportale:''' Kunden sehen ihre offenen Posten, Aufträge und Lieferscheine. Jeder Kunde sieht nur seine eigenen Daten.
* '''Statusseiten:''' Endkunden fragen den Stand einer Bestellung, eines Auftrags oder einer Reparatur über eine Nummer ab.


===Interne Microservices und Automatisierungen===
==== Mobile Anwendungen und Außendienst ====
* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Arbeitsbeginn, Pause und Ende am Smartphone. Die Daten landen direkt in OBS.
* '''Scanner und Lagergeräte:''' Wareneingang, Inventur und Kommissionierung direkt in OBS, ohne zwischengeschaltete Software.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material und laden Fotos hoch.
* '''Geräte in Sekunden einrichten:''' Ein Zugangscode als QR-Code bringt Adresse und Zugangsdaten mit einem Scan auf das Gerät.


* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
==== Anbindung von Drittsystemen ====
* '''Verbindung mehrerer Standorte:''' Verteilte Systeme tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
* '''Webshops:''' Der Shop meldet Bestellungen direkt an OBS und fragt Bestände und Preise ab.
* '''Datenbereitstellung für Dashboards und Auswertungen:''' BI-Tools (Power BI, Grafana, ...) lesen aufbereitete Kennzahlen direkt aus OBS.
* '''Buchhaltungs- und ERP-Systeme:''' Austausch von Belegen, Stammdaten und Buchungen in beide Richtungen.
* '''CRM- und Marketing-Werkzeuge:''' Personendaten, Aktivitäten oder Mailing-Empfänger bleiben abgeglichen.
* '''Logistikdienstleister:''' Versandaufträge gehen hinaus, Sendungsinformationen kommen zurück.


===Was bedeutet das wirtschaftlich?===
==== Automatische Rückmeldungen (WebHooks) ====
* '''Rückruf-Adressen für Fremdsysteme:''' OBS legt für einen Vorgang eine Adresse an, die genau einmal gilt, z.B. für einen Bezahl- oder Versanddienst. Dessen Rückmeldung landet in OBS und wird dort weiterverarbeitet.
* '''Automatisierungsplattformen''' stoßen über gewöhnliche Endpunkte Vorgänge in OBS an.


* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
==== Geschäftspartner (B2B) ====
* '''Fehler werden weniger.''' Jede manuelle Stelle ist eine mögliche Fehlerquelle; jede Automatisierung eine Stelle, an der nichts mehr schiefgehen kann.
* '''Lieferanten:''' Bestellungen gehen automatisch hinaus, Auftragsbestätigungen und Lieferavise kommen zurück.
* '''Neue Geschäftsmodelle werden möglich.''' Kunden- und Lieferantenportale, Self-Service-Funktionen, App-Anbindungen lassen sich aufbauen, ohne ein zweites System pflegen zu müssen.
* '''Großkunden''' bestellen direkt aus ihrem eigenen System.
* '''Bestehende Software bleibt verbunden.''' Statt eine vorhandene Anwendung ablösen zu müssen, kann sie über den REST-Server an OBS angedockt werden - in beiden Richtungen.
* '''Maschine-zu-Maschine mit mTLS:''' Nur Partnersysteme mit einem gültigen Client-Zertifikat sprechen mit OBS.
* '''Skaliert mit:''' Was klein anfängt (ein einzelner Endpunkt für eine Webseite) kann zu einer kompletten Integrations-Plattform ausgebaut werden, ohne dass die Grundlage gewechselt werden muss.


==Architektur im Überblick==
==== Interne Automatisierungen ====
* '''Eigene Hilfswerkzeuge''' für Sammelaktionen, Berichte oder zeitgesteuerte Abläufe.
* '''Mehrere Standorte''' tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
* '''Dashboards und BI-Werkzeuge''' lesen aufbereitete Kennzahlen direkt aus OBS.


Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:
== Seiten in diesem Bereich ==


=== Einrichten und betreiben ===
{| class="wikitable"
{| class="wikitable"
! Baustein    !! Tabelle              !! Zweck
! Seite !! Wofür
|-
| Server      || RESTSRV_SERVER      || TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
|-
|-
| Bindung      || RESTSRV_BINDINGS    || IP-Adresse + Port pro Server
| [[OBS/Kostenpflichtige Module/REST-Server/Einrichtung|Einrichtung]] || Schritt für Schritt vom Server-Profil bis zum ersten erfolgreichen Aufruf.
|-
|-
| Zugang      || RESTSRV_ACCOUNT      || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
| [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]] || Portfreigabe, Reverse-Proxy, VPN und eigener Server im Vergleich.
|-
|-
| Endpunkt    || RESTSRV_ENDPOINTS    || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
| [[OBS/Kostenpflichtige Module/REST-Server/Pflege|Pflege]] || Server-Profile, Bindungen, Zugänge und Endpunkte in einem Fenster: TLS, Rate-Limits, Zertifikate, API-Key, CORS, mTLS, JWT, Pfad-Templates und Freischaltungen.
|-
|-
| Berechtigung || RESTSRV_ACCESS      || Verbindet Zugang und Endpunkt
| [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|Zertifikatserneuerung]] || Zertifikate automatisch beantragen und erneuern lassen.
|-
|-
| Idempotenz  || RESTSRV_IDEMPOTENCY  || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
| [[OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]] || Geräte per QR-Code einrichten und den Server ohne öffentliches Zertifikat absichern.
|-
|-
| Sitzung      || RESTSRV_TOKEN        || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
| [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] || Protokoll, Statistik, Konsole, Reverse-Proxy und Wartung der Tabellen.
|-
| Protokoll   || RESTSRV_PROTO        || Laufende Ereignisse, Fehler, Audit-Einträge
|-
| Statistik    || RESTSRV_STATS        || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
|}
|}


Eine Anfrage durchläuft folgende Stationen:
=== Entwickeln ===
 
# Rate-Limit-Prüfung (pro API-Key bzw. IP und global, Schwellen je Server-Profil)
# Andrangsgrenze des Server-Profils (''Max. parallel'') - bei Überschreitung '''503''' mit ''Retry-After''
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Prüfung - Signatur, Ablauf und Sitzung (sofern für den Zugang aktiviert)
# Routing: Auflösung des Pfads über die Pfad-Templates der Endpunkte
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Entpacken des Anfragekörpers, sofern er mit ''Content-Encoding: gzip'' gesendet wurde
# Idempotenz-Prüfung bei POST/PUT/PATCH/DELETE - der Header ''Idempotency-Key'' ist dort '''Pflicht'''
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# Festschreiben des Ergebnisses im Idempotenz-Speicher (sofern in Schritt 9 reserviert)
# JSON-Antwort und Statistik-Eintrag
 
{{Hinweis|'''Die Reihenfolge ist kein Zufall.''' Das Entpacken liegt '''hinter'''
der Authentifizierung, damit ein Unbefugter dem Server keine Rechenzeit für eine
Dekompressionsbombe abverlangen kann - und '''vor''' der Idempotenz-Reservierung,
damit eine abgewiesene Anfrage keinen ''Idempotency-Key'' verbrennt.
 
'''Der Normalfall erzeugt keine Protokollzeile.''' Bis 08/2026 schrieb jede
Anfrage eine Zeile nach RESTSRV_PROTO; sie ist entfallen, weil RESTSRV_STATS
zu derselben Anfrage IP, Zugang, Endpunkt, Methode, Pfad, Status, Laufzeit und
dieselbe Korrelations-ID trägt - und länger aufbewahrt wird. Das Protokoll trägt
seitdem nur noch Auffälligkeiten.}}
 
==Adressierung==
 
Ein Endpunkt wird über ein '''Pfad-Template''' angesprochen, das den Pfad nach dem Host beschreibt und Platzhalter enthalten kann:
 
http://[Hostadresse][:Port][Pfad-Template]
 
Beispiele:
 
https://api.meinserver.de/kalender/v1
https://api.meinserver.de/orders/{uid}
https://api.meinserver.de/orders/{uid}/modules/{code}
 
Statische Segmente müssen exakt passen; Platzhalter in geschweiften Klammern (z.B. {uid}) matchen einen beliebigen Wert und stehen im Skript als Pfad-Parameter zur Verfügung. Eine Versionskennung wird als statisches Segment ins Template aufgenommen (z.B. /kalender/v1), um eine Funktionalität zu verändern, ohne bestehende Konsumenten zu brechen. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].
 
==Unterstützte HTTP-Methoden==
 
Der Server akzeptiert die Methoden '''GET''', '''POST''', '''PUT''', '''DELETE''' und '''PATCH''' sowie '''OPTIONS''' (CORS-Preflight, ohne Skript-Aufruf). Jede Methode wird im Endpunkt-Skript als gleichnamige Prozedur implementiert - '''mit einer Ausnahme''': ''Delete'' ist in der Skriptsprache ein reservierter Name und lässt sich nicht als Prozedur deklarieren. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
 
Fehlt die zur Methode passende Prozedur, antwortet der Server mit '''405''' und
nennt im Header ''Allow'' die Verben, die dieses Skript tatsächlich anbietet.
 
==Kompression==
 
Der Server packt Antworten mit '''gzip''', wenn der Client sie annimmt. Ausgehandelt wird über den Anfrage-Header <code>Accept-Encoding</code>; die Antwort trägt dann <code>Content-Encoding: gzip</code> und <code>Vary: Accept-Encoding</code> - bei einer CORS-Anfrage steht dort <code>Vary: Origin, Accept-Encoding</code>, also '''eine''' Zeile mit beiden Bedingungen. Browser, <code>curl --compressed</code> und die gängigen HTTP-Bibliotheken entpacken selbstständig - für den Konsumenten ändert sich nichts ausser der übertragenen Datenmenge.
 
Gepackt wird nur, wo es etwas bringt:
 
* Nur JSON (auch ''problem+json'' und ''ndjson''), XML, JavaScript, SVG und alles unter ''text/'' - darunter Text, CSV und HTML. Bereits komprimierte Typen - PDF, Bild, ZIP, Video - werden durch gzip '''grösser''', nicht kleiner.
* Erst ab '''1024 Byte'''. Darunter kostet der gzip-Rahmen mehr, als der Inhalt einspart.
* '''Nicht''' bei Dateiantworten, nicht bei Teilauslieferungen (206) und nicht bei Antworten ohne Körper (204, 304).
* Nicht, wenn das Endpunkt-Skript den Header <code>Content-Encoding</code> selbst gesetzt hat - dann gehört die Antwort dem Skript.
 
'''deflate''' wird in '''keiner''' Richtung unterstützt. Der Wert ist historisch uneindeutig - die einen senden RFC-1950-gerahmt, die anderen roh -, und wer ihn nennt, beherrscht ohnehin gzip. Eine Anfrage mit <code>Content-Encoding: deflate</code> wird mit 415 abgewiesen.
 
Abschalten lässt sich das Packen je Server-Profil über den Haken ''Keine Kompression'' (siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]). Der Haken betrifft ausschliesslich die Antwortrichtung.
 
===Komprimierte Anfragen===
 
In der Gegenrichtung nimmt der Server '''gzip''' entgegen: Trägt eine Anfrage den Header <code>Content-Encoding: gzip</code>, wird der Körper entpackt, bevor ihn jemand liest. Das Endpunkt-Skript merkt davon nichts.
 
{| class="wikitable"
{| class="wikitable"
! Anfrage                                              !! Antwort
! Seite !! Wofür
|-
| <code>Content-Encoding</code> fehlt oder <code>identity</code> || normale Verarbeitung; ab 10 MB Körpergrösse '''413'''
|-
|-
| <code>gzip</code>                                    || Körper wird entpackt
| [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] || Header, Ablauf einer Anfrage, Fehlerformat, Fehlercodes, Rate-Limit und Idempotenz.
|-
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
| [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]] || Anmelden, Token erneuern, Abmelden und das Anmeldeskript.
|-
|-
| Gepackter Körper bei einem Datei-Upload              || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
| [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] || Aufbau der Endpunkt-Skripte mit Reader und Writer.
|-
|-
| Entpackter Körper über '''10 MB'''                    || '''413''' <code>PAYLOAD_TOO_LARGE</code>
| [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]] || Dateien entgegennehmen, auch fortsetzbar in Teilstücken.
|-
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
| [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]] || Dateien ausliefern, auch in Teilen.
|}
|}


{{Hinweis|Für einen gepackten Anfragekörper gelten '''zwei''' Grenzen. Beide zählen den '''entpackten''' Inhalt, und beide greifen bereits '''während''' des Entpackens - ein Körper, der sie reisst, belegt den Speicher gar nicht erst:
=== Beispiele ===
 
Vollständige, lauffähige Anbindungen zum Nachbauen. Übersicht: [[OBS/Kostenpflichtige Module/REST-Server/Beispiele|Beispiele]].
* '''10 MB''' absolut. Dieselbe Grenze, die auch für einen ungepackten Körper gilt.
* '''das 400fache''' der gesendeten Grösse, '''mindestens aber 64 KB'''. Damit wird eine ''Dekompressionsbombe'' - wenige Kilobyte, die sich auf Hunderte Megabyte aufblähen - schon nach wenigen Prozent abgebrochen. Der Boden von 64 KB sorgt dafür, dass die Verhältnisrechnung winzige Körper gar nicht erst trifft: ein 100-Byte-Körper darf sich auf 64 KB entpacken, nicht nur auf 40 KB.
 
Die zweite Grenze trifft normale Nutzlasten nicht. Gemessen erreichen echte JSON-Körper Verhältnisse von 24:1 bis 40:1, und selbst eine Liste aus zehntausenden identischen Zeilen kommt nur auf rund 340:1 - mehr gibt das Verfahren für wiederholte Datensätze nicht her. Über 400:1 kommt nur, wer sehr lange Läufe desselben Zeichens sendet.
 
Für Datei-Uploads gilt keine der beiden Grenzen - dort zählt allein die je Endpunkt eingestellte Maximalgrösse.}}
 
==Persistente Verbindungen (Keep-alive)==
 
Der Server hält eine Verbindung nach der Antwort '''offen''', statt sie zu
schliessen. Ein Client, der mehrere Anfragen hintereinander stellt - eine App,
die eine Liste seitenweise abholt -, spart damit je Folgeanfrage den Aufbau von
TCP-Verbindung und TLS-Sitzung.
 
{| class="wikitable"
{| class="wikitable"
! Grenze !! Wert !! Bedeutung
! Seite !! Wofür
|-
|-
| Leerlauf || '''10 Sekunden''' || Passiert auf der Verbindung so lange nichts, wird sie geschlossen
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Daten-Abruf mit JWT-Anmeldung|Daten-Abruf mit JWT-Anmeldung]] || Daten aus OBS auf einer Webseite anzeigen, mit Anmeldung.
|-
|-
| Anfragen je Verbindung || '''100''' || Danach schliesst der Server geordnet, der Client baut neu auf
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper|Datensatz anlegen mit JSON-Körper]] || Datensätze eines Fremdsystems anlegen, abrufen und ändern.
|-
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Pfad-Parameter]] || Einzelne Datensätze über Platzhalter im Pfad ansprechen.
|-
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz|Schreibzugriff mit Statuscodes, ETag und Idempotenz]] || Sicher schreiben aus einer mobilen App.
|-
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Datei-Upload und Ablage]] || Fotos und Dokumente zu einem Vorgang hochladen und ablegen.
|}
|}


Beides ist für den Konsumenten unkritisch: Eine geschlossene Verbindung ist kein
== Grundlagen ==
Fehler, jede HTTP-Bibliothek baut sie bei der nächsten Anfrage selbst wieder auf.
Wer viele Anfragen hintereinander stellt, gewinnt aber deutlich, wenn er seinen
Client die Verbindung wiederverwenden lässt (''Connection: keep-alive'' ist der
Standard von HTTP/1.1, die meisten Bibliotheken tun es von allein).
 
{{Hinweis|'''Die Leerlaufgrenze gilt für jeden Lesevorgang der Verbindung''',
nicht nur für das Warten auf die nächste Anfrage. Ein Client, der seinen
Anfragekörper nur tropfenweise sendet und dazwischen länger als 10 Sekunden
pausiert, verliert die Verbindung mitten im Senden.}}
 
Die Werte sind bewusst knapp gewählt: Der Server fährt einen eigenen Thread je
Verbindung, eine leerlaufende Verbindung kostet also nicht bloss einen
Dateizeiger. Sie sind keine Lastgrenze - dafür gibt es ''Max. Verbindungen'' und
''Max. parallel'' am Server-Profil (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]).
 
==Datei-Uploads==
 
Endpunkte, die dafür freigeschaltet sind (<code>re_upload</code>), nehmen Dateien
per <code>multipart/form-data</code> oder als fortsetzbaren '''Resumable-Upload'''
(<code>Content-Range</code>) entgegen. Die maximale Grösse wird pro Endpunkt
festgelegt (<code>re_upload_size</code>, Standard 25&nbsp;MB); Überschreitung
ergibt 413, ein Upload an einen nicht freigeschalteten Endpunkt 415. Der Server
legt die Datei temporär ab und übergibt dem Skript den Pfad; die weitere
Verarbeitung (z.B. DMS-Ablage) übernimmt das Skript. Details:
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
 
==Doppelte Sendungen abfangen (Idempotenz)==
 
Ein Client, der nach einem Timeout dieselbe Anfrage erneut schickt, darf keine
Zweitbuchung auslösen. Der Server erledigt das selbst: Jeder Aufruf mit
'''POST''', '''PUT''', '''PATCH''' oder '''DELETE''' muss den Header
<code>Idempotency-Key</code> tragen; der Server merkt sich Schlüssel und Ergebnis
in '''RESTSRV_IDEMPOTENCY'''. Eine Wiederholung mit demselben Schlüssel und
demselben Inhalt bekommt die '''gespeicherte Antwort''' zurück - das
Endpunkt-Skript läuft gar nicht erst an.
 
{{Achtung|'''Der Header ist Pflicht, nicht optional.''' Ein schreibender Aufruf
'''ohne''' <code>Idempotency-Key</code> wird mit '''400'''
<code>IDEMPOTENCY_KEY_MISSING</code> abgewiesen, und das Endpunkt-Skript läuft
nicht an.
 
Das war bis v1.21 anders: fehlte der Header, lief die Anfrage ungeschützt durch.
Der Schutz gegen eine Doppelbuchung stand damit in der Zusage des Clients und
nicht in einer Prüfung des Servers - ein Wiederholversuch nach Zeitüberschreitung
buchte ein zweites Mal. Konsumenten, die bisher ohne den Header schreiben, müssen
angepasst werden.}}
 
* '''Pflicht nur für schreibende Verben.''' ''GET'' braucht keinen Schlüssel und kennt die Mechanik nicht.
* '''Der JWT-Endpunkt ist ausgenommen.''' Anmelden, Erneuern und Abmelden laufen vor der Adressauflösung und brauchen keinen Schlüssel.
* '''Kein Schalter am Endpunkt.''' Die Mechanik greift für jeden Endpunkt automatisch.
* '''Das Skript muss nichts tun.''' Eine eigene Idempotenz-Logik im Skript ist nicht nötig.
* '''Pro Vorgang ein Schlüssel''', über alle Wiederholversuche hinweg unverändert - nicht bei jedem Versuch neu erzeugt.
 
Details und die Statuscodes: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt Idempotenz.
 
==Sitzungen und Abmelden==
 
Ein JWT trägt seine Gültigkeit in sich: der Server prüft Signatur und Ablauf und
braucht dafür keine Datenbank. Genau deshalb liesse sich ein ausgegebener Token
von sich aus auch nicht mehr zurückziehen - ein verlorenes Gerät wäre bis zum
Ablauf des Tokens weiter nutzbar.
 
Der Server führt deshalb zu jedem ausgestellten Token-Paar eine Zeile in
'''RESTSRV_TOKEN''' und prüft jeden Zugriff dagegen. Daraus ergeben sich drei
Eigenschaften:
 
* '''Abmelden wirkt sofort.''' Ein ''DELETE'' auf den JWT-Endpunkt sperrt die Sitzung; alle Token dieser Sitzung sind damit unmittelbar ungültig, auch die noch nicht abgelaufenen. Anmelden, Erneuern und Abmelden laufen also über einen einzigen Endpunkt, und für das Abmelden ist kein Skript nötig.
* '''Ein Refresh-Token gilt genau einmal.''' Beim Erneuern wird es entwertet. Wird es später erneut vorgelegt, gilt das als Diebstahl oder Fehlfunktion: die betroffene Sitzung wird komplett gesperrt und der Vorfall protokolliert.
* '''Alle Geräte abmelden.''' Ein gewöhnlicher Endpunkt kann über den Aufruf ''oWriter.JwtRevoke('all')'' auch alle Sitzungen eines Benutzers sperren - der Support-Fall „Gerät verloren".
 
{{Achtung|Mit der Einführung dieser Prüfung verlieren '''alle vorher
ausgestellten Token''' ihre Gültigkeit, weil sie zu keiner Sitzung gehören.
Angemeldete Konsumenten müssen sich nach dem Update einmalig neu anmelden.}}
 
Der Speicher pflegt sich selbst: Zeilen werden gelöscht, sobald sowohl das
Access- als auch das Refresh-Token abgelaufen sind. Details und die Skript-Seite:
[[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
 
==Fehlerformat==
 
Jede Fehlerantwort des Servers hat dieselbe Form: ein einziges ''error''-Objekt
mit maschinenlesbarem Code, Support-Kennung, Meldung und Korrelations-ID:
 
<pre>
{
  "error": {
    "code":    "AUTH_EXPIRED",
    "uid":    "Y00E2RTPDY",
    "message": "Ungültiges oder abgelaufenes Token",
    "traceId": "20260817T091233123-00001A"
  }
}
</pre>
 
* '''code''' - sprechender Bezeichner (z.B. ''AUTH_EXPIRED'', ''NOT_FOUND'', ''RATE_LIMITED'', ''INTERNAL_ERROR''), an dem ein Client seine Reaktion festmachen kann, ohne Texte auszuwerten.
* '''uid''' - OBS-Kennung der Codestelle. Für die Support-Recherche gedacht, nicht zur Auswertung im Client.
* '''message''' - Text für den Client. Interne Fehlerdetails stehen nie darin, sondern ausschliesslich im Protokoll '''RESTSRV_PROTO'''.
* '''traceId''' - Korrelations-ID. Steht zusätzlich im Header ''X-Trace-Id'' und in jeder zugehörigen Logzeile.
 
Ein Endpunkt-Skript kann eigene Codes setzen; siehe
[[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
 
{{Achtung|''Fehlercode'', ''Nachricht'' und ''traceId'' stehen '''nur''' im
''error''-Objekt, nicht flach daneben - der Wert von
''Fehlercode'' heisst jetzt ''error.uid'', ''Nachricht'' entspricht
''error.message''. Clients, die die flachen Felder auswerten, müssen angepasst
werden.}}
 
==Sicherheitsmerkmale==
 
Der REST-Server enthält eine Reihe von Schutzmechanismen:
 
* '''Rate-Limit:''' Standardmässig max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro API-Key (Account) bzw. IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 mit ''Retry-After''-Header zurückgegeben. Die vier Schwellen lassen sich '''pro Server-Profil''' hinterlegen; die Zähler laufen ebenfalls getrennt je Profil, ein überlastetes Profil bremst das andere also nicht mit aus. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
* '''Body-Limit:''' max. 10 MB Request-Body (JSON), max. 1024 Zeichen pro Header- oder Query-Parameter. Datei-Uploads laufen über einen separaten Pfad und sind pro Endpunkt auf <code>re_upload_size</code> MB begrenzt (Standard 25&nbsp;MB).
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Widerrufbare Token:''' Jedes ausgestellte Token-Paar gehört zu einer Sitzung in '''RESTSRV_TOKEN''' und wird bei '''jedem''' Zugriff dagegen geprüft. Eine Abmeldung wirkt damit sofort und nicht erst mit dem Ablauf des Tokens; ein Refresh-Token gilt genau einmal. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
* '''Reserviertes Präfix:''' Parameter-Namen mit Präfix ''_OBS_'' können von aussen nicht gesetzt werden, sie sind für den Server reserviert (z.B. JWT-Claims).
* '''Geblockte Header:''' ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key'' werden nicht an das Skript durchgereicht.
* '''TLS:''' Bei Profilen mit aktivem TLS fährt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur für ein dediziertes Debug-Profil möglich.
* '''HSTS:''' Antworten eines TLS-Profils tragen ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse danach ein Jahr lang nur noch über HTTPS an. Beim Debug-Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
* '''mTLS''' (Mutual TLS): erzwingt, dass jeder Client ein gültiges Client-Zertifikat vorlegt. Optional kann pro Zugang ein erwarteter Subject-DN hinterlegt werden.
* '''DNS-Cache:''' Host-zu-IP-Auflösungen für die Zugangs-Host-Prüfung werden 5 Minuten gecached.
* '''Automatische Zertifikatserneuerung:''' Ein TLS-Profil kann sein Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Der Dienst prüft wöchentlich, ob der Server dafür von aussen erreichbar ist, und tauscht das Zertifikat anschliessend ohne Neustart des Dienstes - nur das betroffene Profil startet neu. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
 
==Protokoll==
 
Die Tabelle '''RESTSRV_PROTO''' enthält alle relevanten Ereignisse: erfolgreiche und abgelehnte Anfragen, TLS-/JWT-Fehler, Bindungs-Ereignisse, Skript-Fehler. Einträge sind nach Datum, Uhrzeit und Host (IP oder Account-Name) sortiert. Das Protokoll ist die erste Anlaufstelle bei Störungen. Jede Antwort trägt zudem eine Korrelations-ID (Response-Header ''X-Trace-Id''), die in den Protokoll-Einträgen wiederzufinden ist.
 
Läuft der REST-Server hinter einem Reverse-Proxy, steht als Host die IP-Adresse des Proxys. Schickt der Proxy den Header ''X-Forwarded-For'' mit, hängt der Server dessen Wert in Protokoll und Konsole als <code>[xff=…]</code> an den Eintrag an. Der Wert ist eine Angabe des Absenders und wird nur protokolliert. Host-Beschränkung und Rate-Limit verwenden immer die IP-Adresse der Verbindung. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].
 
==Statistik==
 
Die Tabelle '''RESTSRV_STATS''' enthält eine Statistik aller bearbeiteten Anfragen
mit IP, Zugang, Endpunkt, Methode, angefragtem Pfad, HTTP-Status und Laufzeit in
Millisekunden. Dazu kommen zwei Felder, die den Sprung ins Protokoll erlauben:
 
* '''rs_trace''' - dieselbe Korrelations-ID, die auch im Header ''X-Trace-Id'' und in jeder zugehörigen Protokollzeile steht. Damit findet man zu einer auffälligen Statistikzeile alle Protokolleinträge derselben Anfrage.
* '''rs_server''' - das Server-Profil, über das die Anfrage hereinkam. Bei mehreren Profilen (Public-TLS neben Internal-mTLS) ist das die einzige Angabe, an der sich der Weg ablesen lässt.
 
Weil der Normalfall keine Protokollzeile mehr schreibt, ist RESTSRV_STATS die
vollständige Sicht auf den Betrieb - RESTSRV_PROTO die auf die Auffälligkeiten.


Aufruf der Statistik:
=== Bausteine ===
 
Alle Bausteine pflegen Sie in OBS. Jeder Baustein hat eine eigene Tabelle.
* Aus der Endpunkt-Liste: F8 zeigt die Statistik des markierten Endpunkts.
* Aus der Zugänge-Liste: F8 zeigt die Statistik des markierten Zugangs.
 
==Konsole==
 
Wird der REST-Server nicht als Dienst, sondern interaktiv gestartet, erscheint eine
farbige Konsole mit Live-Log und einem '''fixierten Kopfbereich''', der die gerade
laufenden Anfragen zeigt und sich fortlaufend aktualisiert.


{| class="wikitable"
{| class="wikitable"
! Befehl !! Wirkung
! Baustein !! Tabelle !! Zweck
|-
|-
| ''show <handle>'' || Details einer Anfrage: Request-Header, Protokollzeilen, Antwort. JSON wird farbig formatiert. ''<handle>'' ist die Kennung aus der Abschlusszeile der Anfrage (z.B. ''7F''), '''keine''' laufende Nummer
| Server-Profil || <code>RESTSRV_SERVER</code> || TLS-Einstellungen und Grenzen eines eigenen HTTP-Servers. Mehrere Profile sind möglich.
|-
|-
| ''1'' … ''9'' || Auswahl im Kopfbereich - kürzer als ''show'' für die gerade sichtbaren Anfragen. Mit ''mouse on'' auch per Klick
| Bindung || <code>RESTSRV_BINDINGS</code> || IP-Adresse und Port, auf denen ein Server-Profil lauscht.
|-
|-
| ''ps'' || Listet die gerade laufenden Anfragen auf
| Zugang || <code>RESTSRV_ACCOUNT</code> || API-Key, optionale Host- und CORS-Beschränkung, mTLS und JWT-Anmeldung. Einem Server-Profil fest zugeordnet.
|-
|-
| ''level <stufe>'' || Anzeigestufe des Live-Logs: ''quiet'' , ''normal'' oder ''debug''. Ohne Parameter wird die aktuelle Stufe genannt
| Endpunkt || <code>RESTSRV_ENDPOINTS</code> || Pfad-Template und Skript. Einem Server-Profil fest zugeordnet.
|-
|-
| ''filter <ausdruck>'' || Blendet aus, was nicht passt: ''path=<text>'', ''account=<name>'', ''status>=<code>''. ''filter aus'' hebt die Einschränkung auf
| Berechtigung || <code>RESTSRV_ACCESS</code> || Verbindet Zugang und Endpunkt.
|-
|-
| ''panel on&#124;off'' || Fixierten Kopfbereich ein-/ausschalten. '''Ausgeschaltet''' lässt sich der Rückblick-Puffer des Konsolenfensters wieder scrollen
| Idempotenz || <code>RESTSRV_IDEMPOTENCY</code> || Speichert die Antwort zu jedem ''Idempotency-Key''.
|-
|-
| ''mouse on&#124;off'' || Klick-Auswahl im Kopfbereich. '''Eingeschaltet''' ist das Markieren von Text mit der Maus nicht mehr möglich
| Sitzung || <code>RESTSRV_TOKEN</code> || Sitzungen der JWT-Anmeldung. Grundlage für das sofortige Abmelden.
|-
|-
| ''help'' / ''?'' || Zeigt diese Liste in der Konsole
| Protokoll || <code>RESTSRV_PROTO</code> || Auffälligkeiten: abgewiesene und fehlerhafte Anfragen, Start, Bindungen, Zertifikate, Skriptfehler.
|-
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
| Statistik || <code>RESTSRV_STATS</code> || Eine Zeile je verarbeiteter Anfrage mit Zugang, Endpunkt, Status und Laufzeit.
|}
|}


{{Hinweis|Der Anzeigefilter wirkt '''nur auf die Anzeige'''. Was die Konsole
=== So läuft eine Anfrage ===
ausblendet, steht vollständig in RESTSRV_PROTO - es geht nichts verloren.}}
# Der Client verbindet sich per HTTPS mit einer Bindung eines Server-Profils.
 
# Der Server prüft Rate-Limit und Auslastung des Profils.
Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.
# Er ordnet die Anfrage über den API-Key einem Zugang zu und prüft Host, Origin und gegebenenfalls das Client-Zertifikat.
# Verlangt der Zugang JWT, prüft er Token und Sitzung.
# Er findet den Endpunkt über das Pfad-Template und prüft die Berechtigung des Zugangs.
# Bei schreibenden Anfragen prüft er den ''Idempotency-Key''.
# Das Skript des Endpunkts läuft. Schreibende Anfragen laufen in einer Datenbanktransaktion.
# Der Server sendet die Antwort mit einer Korrelations-ID und schreibt die Statistik.


==Weiterführende Seiten==
Die vollständige Reihenfolge mit allen Statuscodes beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Ablauf einer Anfrage|HTTP-Schnittstelle]].


* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
=== Sicherheit ===
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
Der REST-Server ist für den Betrieb im Internet gebaut:
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]] - Portfreigabe, Reverse-Proxy oder VPN im Vergleich
* '''Verschlüsselung ist Pflicht.''' Server-Profile sprechen ausschließlich TLS 1.2 mit Forward Secrecy. Klartext gibt es nur mit dem Haken '''kein SSL (Plain-HTTP - nur für Debug!)'''. Zertifikate erneuert der Dienst auf Wunsch selbst. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Server-Profil|Pflege]] und [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|Zertifikatserneuerung]].
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] - automatische Zertifikate über http-01 oder dns-01
* '''Ein API-Key je Zugang.''' Jeder Zugang sieht nur die Endpunkte, für die er freigeschaltet ist. Zusätzlich beschränken Sie ihn auf einen Host, auf erlaubte Browser-Origins oder per mTLS auf ein Client-Zertifikat. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Absicherung eines Zugangs|Pflege]].
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* '''JWT-Anmeldung mit Sitzungen.''' Benutzer melden sich einzeln an. Ein Abmelden wirkt sofort. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]].
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* '''Rate-Limit und Andrangsgrenze''' bremsen Missbrauch und Lastspitzen. Gezählt wird je API-Key, ohne Key je IP-Adresse.
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* '''Keine Doppelbuchungen.''' Schreibende Anfragen tragen einen ''Idempotency-Key''. Eine Wiederholung wirkt nur einmal. Siehe [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* '''Keine internen Details nach außen.''' Fehlerantworten sind allgemein gehalten. Den Grund findet der Betreiber über die Korrelations-ID im Protokoll. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]].
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]] - Dateien ausliefern, Range/Resume, öffentliche Artefakte
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]

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

REST-Server

Der REST-Server ist die universelle Schnittstelle Ihrer OBS-Installation nach außen. Webseiten, Apps, Geräte, Kundensysteme und Cloud-Dienste lesen Daten direkt aus OBS oder liefern neue Daten direkt in OBS ab. Diese Seite zeigt, was der REST-Server leistet, und führt Administratoren und Entwickler zu den passenden Unterseiten.

HINWEIS: Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.

Sie erreichen das Modul über Stammdaten → Z Weitere Stammdaten → REST-Server.

Nutzen

Statt Daten zu exportieren, per Mail zu verschicken und woanders wieder einzulesen, holen sich angebundene Systeme genau die Information, die sie brauchen – in dem Moment, in dem sie sie brauchen. Was bisher nur manuell, per Datei-Import oder über Spezialschnittstellen ging, lässt sich automatisieren. Jeder Anwendungsfall wird einmal eingerichtet und läuft danach von selbst.

Technisch ist der REST-Server ein in OBS integrierter HTTPS-Dienst. Jeder Endpunkt hat eine eigene Adresse, ein eigenes Skript und eigene Berechtigungen. Die Skripte pflegen Sie direkt in OBS. Antworten liefert der Server als JSON oder als Datei. Externe Systeme erhalten keinen Zugriff auf die Datenbank. Sie sehen nur, was ein Endpunkt-Skript freigibt.

Der REST-Server ist damit ein Werkzeugkasten: Was an Daten oder Funktionen in OBS verfügbar ist, können Sie über einen Endpunkt nach außen anbieten oder von außen entgegennehmen. Die Bandbreite reicht vom einfachen Lese-Endpunkt für eine Webseite bis zur B2B-Anbindung mit getrennten Zugängen je Partner.

Was Sie damit erreichen

  • Manuelle Arbeit fällt weg. Daten fließen direkt, ohne Export, Mail und Import.
  • Weniger Fehler. Jede manuelle Übertragung ist eine Fehlerquelle weniger.
  • Neue Angebote werden möglich. Kunden- und Lieferantenportale, Self-Service und Apps greifen auf OBS zu, ohne dass Sie ein zweites System pflegen.
  • Bestehende Software bleibt. Vorhandene Anwendungen docken über den REST-Server an OBS an, in beide Richtungen.
  • Wächst mit. Ein einzelner Endpunkt für eine Webseite lässt sich zu einer kompletten Integrationsplattform ausbauen, ohne die Grundlage zu wechseln.

Anwendungsbereiche

Die folgenden Einsatzfälle sind Beispiele. Alles, was sich in einem Endpunkt-Skript abbilden lässt, kann der REST-Server bereitstellen.

HINWEIS: Ob für Ihren Anwendungsfall Entwicklungsaufwand entsteht, klärt Ihr OBS-Betreuer mit Ihnen.

Webseiten und Kundenportale

  • Live-Daten auf der eigenen Webseite: Lagerbestände, Verfügbarkeiten, Preise oder Auftragsstatus direkt aus OBS, ohne tägliche Datei-Exporte.
  • Kundenportale: Kunden sehen ihre offenen Posten, Aufträge und Lieferscheine. Jeder Kunde sieht nur seine eigenen Daten.
  • Statusseiten: Endkunden fragen den Stand einer Bestellung, eines Auftrags oder einer Reparatur über eine Nummer ab.

Mobile Anwendungen und Außendienst

  • Mobile Zeiterfassung: Mitarbeiter buchen Arbeitsbeginn, Pause und Ende am Smartphone. Die Daten landen direkt in OBS.
  • Scanner und Lagergeräte: Wareneingang, Inventur und Kommissionierung direkt in OBS, ohne zwischengeschaltete Software.
  • Außendienst-Apps: Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material und laden Fotos hoch.
  • Geräte in Sekunden einrichten: Ein Zugangscode als QR-Code bringt Adresse und Zugangsdaten mit einem Scan auf das Gerät.

Anbindung von Drittsystemen

  • Webshops: Der Shop meldet Bestellungen direkt an OBS und fragt Bestände und Preise ab.
  • Buchhaltungs- und ERP-Systeme: Austausch von Belegen, Stammdaten und Buchungen in beide Richtungen.
  • CRM- und Marketing-Werkzeuge: Personendaten, Aktivitäten oder Mailing-Empfänger bleiben abgeglichen.
  • Logistikdienstleister: Versandaufträge gehen hinaus, Sendungsinformationen kommen zurück.

Automatische Rückmeldungen (WebHooks)

  • Rückruf-Adressen für Fremdsysteme: OBS legt für einen Vorgang eine Adresse an, die genau einmal gilt, z.B. für einen Bezahl- oder Versanddienst. Dessen Rückmeldung landet in OBS und wird dort weiterverarbeitet.
  • Automatisierungsplattformen stoßen über gewöhnliche Endpunkte Vorgänge in OBS an.

Geschäftspartner (B2B)

  • Lieferanten: Bestellungen gehen automatisch hinaus, Auftragsbestätigungen und Lieferavise kommen zurück.
  • Großkunden bestellen direkt aus ihrem eigenen System.
  • Maschine-zu-Maschine mit mTLS: Nur Partnersysteme mit einem gültigen Client-Zertifikat sprechen mit OBS.

Interne Automatisierungen

  • Eigene Hilfswerkzeuge für Sammelaktionen, Berichte oder zeitgesteuerte Abläufe.
  • Mehrere Standorte tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
  • Dashboards und BI-Werkzeuge lesen aufbereitete Kennzahlen direkt aus OBS.

Seiten in diesem Bereich

Einrichten und betreiben

Seite Wofür
Einrichtung Schritt für Schritt vom Server-Profil bis zum ersten erfolgreichen Aufruf.
Öffentliche Freigabe Portfreigabe, Reverse-Proxy, VPN und eigener Server im Vergleich.
Pflege Server-Profile, Bindungen, Zugänge und Endpunkte in einem Fenster: TLS, Rate-Limits, Zertifikate, API-Key, CORS, mTLS, JWT, Pfad-Templates und Freischaltungen.
Zertifikatserneuerung Zertifikate automatisch beantragen und erneuern lassen.
Zugangscode und Zertifikats-Pin Geräte per QR-Code einrichten und den Server ohne öffentliches Zertifikat absichern.
Betrieb und Fehlersuche Protokoll, Statistik, Konsole, Reverse-Proxy und Wartung der Tabellen.

Entwickeln

Seite Wofür
HTTP-Schnittstelle Header, Ablauf einer Anfrage, Fehlerformat, Fehlercodes, Rate-Limit und Idempotenz.
Anmeldung mit JWT Anmelden, Token erneuern, Abmelden und das Anmeldeskript.
Scripting Aufbau der Endpunkt-Skripte mit Reader und Writer.
Datei-Upload Dateien entgegennehmen, auch fortsetzbar in Teilstücken.
Datei-Download Dateien ausliefern, auch in Teilen.

Beispiele

Vollständige, lauffähige Anbindungen zum Nachbauen. Übersicht: Beispiele.

Seite Wofür
Daten-Abruf mit JWT-Anmeldung Daten aus OBS auf einer Webseite anzeigen, mit Anmeldung.
Datensatz anlegen mit JSON-Körper Datensätze eines Fremdsystems anlegen, abrufen und ändern.
Pfad-Parameter Einzelne Datensätze über Platzhalter im Pfad ansprechen.
Schreibzugriff mit Statuscodes, ETag und Idempotenz Sicher schreiben aus einer mobilen App.
Datei-Upload und Ablage Fotos und Dokumente zu einem Vorgang hochladen und ablegen.

Grundlagen

Bausteine

Alle Bausteine pflegen Sie in OBS. Jeder Baustein hat eine eigene Tabelle.

Baustein Tabelle Zweck
Server-Profil RESTSRV_SERVER TLS-Einstellungen und Grenzen eines eigenen HTTP-Servers. Mehrere Profile sind möglich.
Bindung RESTSRV_BINDINGS IP-Adresse und Port, auf denen ein Server-Profil lauscht.
Zugang RESTSRV_ACCOUNT API-Key, optionale Host- und CORS-Beschränkung, mTLS und JWT-Anmeldung. Einem Server-Profil fest zugeordnet.
Endpunkt RESTSRV_ENDPOINTS Pfad-Template und Skript. Einem Server-Profil fest zugeordnet.
Berechtigung RESTSRV_ACCESS Verbindet Zugang und Endpunkt.
Idempotenz RESTSRV_IDEMPOTENCY Speichert die Antwort zu jedem Idempotency-Key.
Sitzung RESTSRV_TOKEN Sitzungen der JWT-Anmeldung. Grundlage für das sofortige Abmelden.
Protokoll RESTSRV_PROTO Auffälligkeiten: abgewiesene und fehlerhafte Anfragen, Start, Bindungen, Zertifikate, Skriptfehler.
Statistik RESTSRV_STATS Eine Zeile je verarbeiteter Anfrage mit Zugang, Endpunkt, Status und Laufzeit.

So läuft eine Anfrage

  1. Der Client verbindet sich per HTTPS mit einer Bindung eines Server-Profils.
  2. Der Server prüft Rate-Limit und Auslastung des Profils.
  3. Er ordnet die Anfrage über den API-Key einem Zugang zu und prüft Host, Origin und gegebenenfalls das Client-Zertifikat.
  4. Verlangt der Zugang JWT, prüft er Token und Sitzung.
  5. Er findet den Endpunkt über das Pfad-Template und prüft die Berechtigung des Zugangs.
  6. Bei schreibenden Anfragen prüft er den Idempotency-Key.
  7. Das Skript des Endpunkts läuft. Schreibende Anfragen laufen in einer Datenbanktransaktion.
  8. Der Server sendet die Antwort mit einer Korrelations-ID und schreibt die Statistik.

Die vollständige Reihenfolge mit allen Statuscodes beschreibt HTTP-Schnittstelle.

Sicherheit

Der REST-Server ist für den Betrieb im Internet gebaut:

  • Verschlüsselung ist Pflicht. Server-Profile sprechen ausschließlich TLS 1.2 mit Forward Secrecy. Klartext gibt es nur mit dem Haken kein SSL (Plain-HTTP - nur für Debug!). Zertifikate erneuert der Dienst auf Wunsch selbst. Siehe Pflege und Zertifikatserneuerung.
  • Ein API-Key je Zugang. Jeder Zugang sieht nur die Endpunkte, für die er freigeschaltet ist. Zusätzlich beschränken Sie ihn auf einen Host, auf erlaubte Browser-Origins oder per mTLS auf ein Client-Zertifikat. Siehe Pflege.
  • JWT-Anmeldung mit Sitzungen. Benutzer melden sich einzeln an. Ein Abmelden wirkt sofort. Siehe Anmeldung mit JWT.
  • Rate-Limit und Andrangsgrenze bremsen Missbrauch und Lastspitzen. Gezählt wird je API-Key, ohne Key je IP-Adresse.
  • Keine Doppelbuchungen. Schreibende Anfragen tragen einen Idempotency-Key. Eine Wiederholung wirkt nur einmal. Siehe HTTP-Schnittstelle.
  • Keine internen Details nach außen. Fehlerantworten sind allgemein gehalten. Den Grund findet der Betreiber über die Korrelations-ID im Protokoll. Siehe Betrieb und Fehlersuche.