Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Seitenliste: Pflege ersetzt Server-Profile, Zugänge und Endpunkte; Zugang gehört fest zu einem Server-Profil [Volltext ersetzt]
 
(16 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{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.
Sie erreichen das Modul über '''Stammdaten → Z Weitere Stammdaten → REST-Server'''.


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.
== Nutzen ==


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.
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.


Aufruf des Moduls in OBS:
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.
'''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''


==Anwendungsbereiche==
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.


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.
=== 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.


{{Hinweis|Dies sind Beispiele. Für die konkrete Entwicklung können, je nach Komplexität, weitere Kosten anfallen.}}
=== Anwendungsbereiche ===
Die folgenden Einsatzfälle sind Beispiele. Alles, was sich in einem Endpunkt-Skript abbilden lässt, kann der REST-Server bereitstellen.


===Webseiten und Kundenportale===
{{Hinweis|Ob für Ihren Anwendungsfall Entwicklungsaufwand entsteht, klärt Ihr OBS-Betreuer mit Ihnen.}}


* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise, Auftragsstatus aus OBS direkt anzeigen, ohne tägliche Datei-Exports.
==== Webseiten und Kundenportale ====
* '''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.
* '''Live-Daten auf der eigenen Webseite:''' Lagerbestände, Verfügbarkeiten, Preise oder Auftragsstatus direkt aus OBS, ohne tägliche Datei-Exporte.
* '''Trackingseiten:''' Status einer Bestellung, eines Auftrags oder einer Reparatur für Endkunden, abrufbar über eine Sendungsnummer.
* '''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 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.


* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
==== Anbindung von Drittsystemen ====
* '''QR-/Barcode-Scanner und Lagergeräte:''' Wareneingang, Inventur, Kommissionierung direkt in OBS abbilden, ohne zwischengeschaltete Software.
* '''Webshops:''' Der Shop meldet Bestellungen direkt an OBS und fragt Bestände und Preise ab.
* '''Außendienst-Apps:''' Techniker sehen ihre Aufträge, dokumentieren Einsätze, erfassen Material - synchronisiert mit 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.


===Anbindung von Drittsystemen===
==== 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.


* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
==== Geschäftspartner (B2B) ====
* '''Buchhaltungs- und ERP-Systeme:''' Bidirektionaler Austausch von Belegen, Stammdaten und Buchungen.
* '''Lieferanten:''' Bestellungen gehen automatisch hinaus, Auftragsbestätigungen und Lieferavise kommen zurück.
* '''CRM- und Marketing-Tools:''' Personendaten, Aktivitäten oder Mailing-Empfänger werden synchron gehalten.
* '''Großkunden''' bestellen direkt aus ihrem eigenen System.
* '''Logistikdienstleister:''' Versandaufträge werden übergeben, Tracking-Informationen zurückgeliefert.
* '''Maschine-zu-Maschine mit mTLS:''' Nur Partnersysteme mit einem gültigen Client-Zertifikat sprechen mit OBS.


===Automatisierte Rückmeldungen (WebHooks)===
==== 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.


* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
== Seiten in diesem Bereich ==
* '''Versanddienste:''' Statusmeldungen (verschickt, zugestellt, retour) werden direkt im passenden Vorgang dokumentiert.
* '''Cloud-Workflows:''' Externe Automatisierungs-Plattformen (Make, Zapier, n8n, ...) stoßen OBS-Vorgänge an oder werden von OBS aus angesprochen.


===Geschäftspartner-Kommunikation (B2B)===
=== Einrichten und betreiben ===
 
{| class="wikitable"
* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
! Seite !! Wofür
* '''Kunden-Schnittstelle:''' Grosskunden bestellen direkt aus ihrem ERP heraus, Stammdaten und Konditionen werden zentral gepflegt.
|-
* '''Sichere Maschine-zu-Maschine-Kommunikation:''' Mit Mutual-TLS (mTLS) wird sichergestellt, dass nur die freigeschalteten Partnersysteme - und niemand sonst - mit OBS sprechen können.
| [[OBS/Kostenpflichtige Module/REST-Server/Einrichtung|Einrichtung]] || Schritt für Schritt vom Server-Profil bis zum ersten erfolgreichen Aufruf.
 
|-
===Interne Microservices und Automatisierungen===
| [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]] || Portfreigabe, Reverse-Proxy, VPN und eigener Server im Vergleich.
 
|-
* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
| [[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.
* '''Verbindung mehrerer Standorte:''' Verteilte Systeme tauschen Daten über definierte Endpunkte aus, ohne offene Datenbankverbindungen.
|-
* '''Datenbereitstellung für Dashboards und Auswertungen:''' BI-Tools (Power BI, Grafana, ...) lesen aufbereitete Kennzahlen direkt aus OBS.
| [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|Zertifikatserneuerung]] || Zertifikate automatisch beantragen und erneuern lassen.
 
|-
===Was bedeutet das wirtschaftlich?===
| [[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.
 
|-
* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
| [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] || Protokoll, Statistik, Konsole, Reverse-Proxy und Wartung der Tabellen.
* '''Fehler werden weniger.''' Jede manuelle Stelle ist eine mögliche Fehlerquelle; jede Automatisierung eine Stelle, an der nichts mehr schiefgehen kann.
|}
* '''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.
* '''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.
* '''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==
 
Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:


=== Entwickeln ===
{| class="wikitable"
{| class="wikitable"
! Baustein    !! Tabelle              !! Zweck
! Seite !! Wofür
|-
| [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] || Header, Ablauf einer Anfrage, Fehlerformat, Fehlercodes, Rate-Limit und Idempotenz.
|-
| [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]] || Anmelden, Token erneuern, Abmelden und das Anmeldeskript.
|-
| [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] || Aufbau der Endpunkt-Skripte mit Reader und Writer.
|-
|-
| Server       || RESTSRV_SERVER      || TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
| [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]] || Dateien entgegennehmen, auch fortsetzbar in Teilstücken.
|-
|-
| Bindung      || RESTSRV_BINDINGS    || IP-Adresse + Port pro Server
| [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]] || Dateien ausliefern, auch in Teilen.
|}
 
=== Beispiele ===
Vollständige, lauffähige Anbindungen zum Nachbauen. Übersicht: [[OBS/Kostenpflichtige Module/REST-Server/Beispiele|Beispiele]].
{| class="wikitable"
! Seite !! Wofür
|-
|-
| Zugang      || RESTSRV_ACCOUNT      || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
| [[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.
|-
|-
| Endpunkt    || RESTSRV_ENDPOINTS    || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
| [[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.
|-
|-
| Berechtigung || RESTSRV_ACCESS      || Verbindet Zugang und Endpunkt
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Pfad-Parameter]] || Einzelne Datensätze über Platzhalter im Pfad ansprechen.
|-
|-
| Protokoll    || RESTSRV_PROTO        || Laufende Ereignisse, Fehler, Audit-Einträge
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz|Schreibzugriff mit Statuscodes, ETag und Idempotenz]] || Sicher schreiben aus einer mobilen App.
|-
|-
| Statistik    || RESTSRV_STATS        || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
| [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Datei-Upload und Ablage]] || Fotos und Dokumente zu einem Vorgang hochladen und ablegen.
|}
|}


Eine Anfrage durchläuft folgende Stationen:
== Grundlagen ==
 
# Rate-Limit-Prüfung (pro API-Key bzw. IP und global)
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Prüfung (sofern für den Zugang aktiviert)
# Routing: Auflösung des Pfads über die Pfad-Templates der Endpunkte
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag
 
==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
=== Bausteine ===
https://api.meinserver.de/orders/{uid}
Alle Bausteine pflegen Sie in OBS. Jeder Baustein hat eine eigene Tabelle.
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 Funktion implementiert. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].
 
==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]].
 
==Sicherheitsmerkmale==
 
Der REST-Server enthält eine Reihe fest verdrahteter Schutzmechanismen:
 
* '''Rate-Limit:''' 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 Schwellen sind serverseitig konfigurierbar.
* '''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.
* '''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.
* '''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.
 
==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.
 
==Statistik==
 
Die Tabelle '''RESTSRV_STATS''' enthält eine Statistik aller bearbeiteten Anfragen mit Zugang, Endpunkt, Methode, HTTP-Status und Laufzeit in Millisekunden. Aufruf der Statistik:
 
* 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. Die wichtigsten Befehle:


{| class="wikitable"
{| class="wikitable"
! Befehl      !! Wirkung
! Baustein !! Tabelle !! Zweck
|-
| Server-Profil || <code>RESTSRV_SERVER</code> || TLS-Einstellungen und Grenzen eines eigenen HTTP-Servers. Mehrere Profile sind möglich.
|-
| Bindung || <code>RESTSRV_BINDINGS</code> || IP-Adresse und Port, auf denen ein Server-Profil lauscht.
|-
| Zugang || <code>RESTSRV_ACCOUNT</code> || API-Key, optionale Host- und CORS-Beschränkung, mTLS und JWT-Anmeldung. Einem Server-Profil fest zugeordnet.
|-
| Endpunkt || <code>RESTSRV_ENDPOINTS</code> || Pfad-Template und Skript. Einem Server-Profil fest zugeordnet.
|-
| Berechtigung || <code>RESTSRV_ACCESS</code> || Verbindet Zugang und Endpunkt.
|-
| Idempotenz || <code>RESTSRV_IDEMPOTENCY</code> || Speichert die Antwort zu jedem ''Idempotency-Key''.
|-
| Sitzung || <code>RESTSRV_TOKEN</code> || Sitzungen der JWT-Anmeldung. Grundlage für das sofortige Abmelden.
|-
|-
| ''show <n>'' || Zeigt die Details zum Debug-Eintrag ''#n'' (z.B. Request-Header, Response-Body), JSON wird farbig formatiert
| 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.
|}
|}


Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.
=== So läuft eine Anfrage ===
# Der Client verbindet sich per HTTPS mit einer Bindung eines Server-Profils.
# Der Server prüft Rate-Limit und Auslastung des Profils.
# 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/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* '''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/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* '''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/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* '''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/Beispiel1|Beispiel: Daten-Abruf mit JWT]]
* '''Rate-Limit und Andrangsgrenze''' bremsen Missbrauch und Lastspitzen. Gezählt wird je API-Key, ohne Key je IP-Adresse.
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel: Datensatz anlegen mit JSON-Body]]
* '''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/Beispiel4|Beispiel: Pfad-Parameter im Routing]]
* '''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/Beispiel5|Beispiel: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]

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.