OBS/Kostenpflichtige Module/RESTServer: Unterschied zwischen den Versionen

Aus OBS Wiki
Zur Navigation springen Zur Suche springen
Keine Bearbeitungszusammenfassung
Keine Bearbeitungszusammenfassung
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Kostenpflichtige Module}}
=REST-Server=
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss ueber den OBS-Support aktiviert werden.}}
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}


Der OBS REST-Server stellt einen frei konfigurierbaren HTTP/HTTPS-Dienst bereit, ueber den externe Teilnehmer auf Funktionen und Daten der OBS-Datenbank zugreifen koennen. Jeder Endpunkt wird ueber ein in OBS gepflegtes Pascal-Script bedient, die Rueckgaben erfolgen ausschliesslich im JSON-Format.
Der OBS REST-Server stellt einen frei konfigurierbaren HTTP/HTTPS-Dienst bereit, über den externe Teilnehmer auf Funktionen und Daten der OBS-Datenbank zugreifen können. Jeder Endpunkt wird über ein in OBS gepflegtes Pascal-Script bedient, die Rückgaben erfolgen ausschliesslich im JSON-Format.


Aufruf des Moduls in OBS:
Aufruf des Moduls in OBS:
Zeile 10: Zeile 10:
==Anwendungsbereiche==
==Anwendungsbereiche==


Typische Einsatzfaelle:
Typische Einsatzfälle:


* Bereitstellung von OBS-Daten fuer Webseiten (Steuerungsdaten, Statistiken, Verfuegbarkeiten)
* Bereitstellung von OBS-Daten für Webseiten (Steürungsdaten, Statistiken, Verfügbarkeiten)
* Anbindung mobiler Endgeraete (Zeiterfassung, QR-Scanner, Lagerlisten)
* Anbindung mobiler Endgeräte (Zeiterfassung, QR-Scanner, Lagerlisten)
* Integration mit Drittsystemen (ERP, Shop, Buchhaltung) ueber JSON-APIs
* Integration mit Drittsystemen (ERP, Shop, Buchhaltung) über JSON-APIs
* Empfang von WebHook-Aufrufen externer Dienste (z.B. Bezahl-Callbacks)
* Empfang von WebHook-Aufrufen externer Dienste (z.B. Bezahl-Callbacks)
* Bereitstellung interner Microservices mit gegenseitiger Authentifizierung (mTLS)
* Bereitstellung interner Microservices mit gegenseitiger Authentifizierung (mTLS)


==Architektur im Ueberblick==
==Architektur im Überblick==


Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:
Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:
Zeile 29: Zeile 29:
| Bindung      || RESTSRV_BINDINGS    || IP-Adresse + Port pro Server
| Bindung      || RESTSRV_BINDINGS    || IP-Adresse + Port pro Server
|-
|-
| Zugang      || RESTSRV_ACCOUNT      || API-Key, optionale Host- und CORS-Beschraenkung, optionale JWT-Konfiguration
| Zugang      || RESTSRV_ACCOUNT      || API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
|-
|-
| Endpunkt    || RESTSRV_ENDPOINTS    || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
| Endpunkt    || RESTSRV_ENDPOINTS    || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
Zeile 35: Zeile 35:
| Berechtigung || RESTSRV_ACCESS      || Verbindet Zugang und Endpunkt
| Berechtigung || RESTSRV_ACCESS      || Verbindet Zugang und Endpunkt
|-
|-
| Protokoll    || RESTSRV_PROTO        || Laufende Ereignisse, Fehler, Audit-Eintraege
| Protokoll    || RESTSRV_PROTO        || Laufende Ereignisse, Fehler, Audit-Einträge
|-
|-
| Statistik    || RESTSRV_STATS        || Aufrufzaehler, Antwortzeiten und HTTP-Status pro Endpunkt
| Statistik    || RESTSRV_STATS        || Aufrufzähler, Antwortzeiten und HTTP-Status pro Endpunkt
|}
|}


Eine Anfrage durchlaeuft folgende Stationen:
Eine Anfrage durchläuft folgende Stationen:


# Rate-Limit-Pruefung (pro IP und global)
# Rate-Limit-Prüfung (pro IP und global)
# Authentifizierung ueber den API-Key (Header ''apikey'')
# Authentifizierung über den API-Key (Header ''apikey'')
# CORS-Pruefung (sofern ''Origin''-Header gesetzt)
# CORS-Prüfung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Pruefung (sofern fuer den Zugang aktiviert)
# Optional: JWT-Prüfung (sofern für den Zugang aktiviert)
# Aufloesung von Endpunkt / Sub-URL / Version
# Auflösung von Endpunkt / Sub-URL / Version
# Pruefung der Berechtigung (Zugang -> Endpunkt)
# Prüfung der Berechtigung (Zugang -> Endpunkt)
# Ausfuehrung des Endpunkt-Skripts (oder WebHook-Antwort)
# Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag


==Adressierung==
==Adressierung==


Ein Endpunkt wird ueber drei Bestandteile angesprochen: Endpunkt-Name, optionale Sub-URL und Version:
Ein Endpunkt wird über drei Bestandteile angesprochen: Endpunkt-Name, optionale Sub-URL und Version:


  http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]
  http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]
Zeile 63: Zeile 63:
  https://api.meinserver.de/zeiterfa/mobile/v2
  https://api.meinserver.de/zeiterfa/mobile/v2


Durch die Versionierung kann eine Endpunkt-Funktionalitaet veraendert werden, ohne bestehende Konsumenten zu brechen.
Durch die Versionierung kann eine Endpunkt-Funktionalität verändert werden, ohne bestehende Konsumenten zu brechen.


==Unterstuetzte HTTP-Methoden==
==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]].
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]].
Zeile 71: Zeile 71:
==Sicherheitsmerkmale==
==Sicherheitsmerkmale==


Der REST-Server enthaelt eine Reihe fest verdrahteter Schutzmechanismen:
Der REST-Server enthält eine Reihe fest verdrahteter Schutzmechanismen:


* '''Rate-Limit:''' max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Ueberschreiten wird HTTP 429 zurueckgegeben.
* '''Rate-Limit:''' max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 zurückgegeben.
* '''Body-Limit:''' max. 10 MB Request-Body, max. 1024 Zeichen pro Header- oder Query-Parameter.
* '''Body-Limit:''' max. 10 MB Request-Body, max. 1024 Zeichen pro Header- oder Query-Parameter.
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Sensible Felder''' (''password'', ''token'', ''secret'', ''apikey'', ''authorization'', ''cookie'', ...) werden in Protokoll-Ausgaben automatisch maskiert.
* '''Reserviertes Praefix:''' Parameter-Namen mit Praefix ''_OBS_'' koennen von aussen nicht gesetzt werden, sie sind fuer den Server reserviert (z.B. JWT-Claims).
* '''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.
* '''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 faehrt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur fuer ein dediziertes Debug-Profil moeglich.
* '''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 gueltiges Client-Zertifikat vorlegt. Optional kann pro Zugang ein erwarteter Subject-DN hinterlegt werden.
* '''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-Aufloesungen fuer die Zugangs-Host-Pruefung werden 5 Minuten gecached.
* '''DNS-Cache:''' Host-zu-IP-Auflösungen für die Zugangs-Host-Prüfung werden 5 Minuten gecached.


==Protokoll==
==Protokoll==


Die Tabelle '''RESTSRV_PROTO''' enthaelt alle relevanten Ereignisse: erfolgreiche und abgelehnte Anfragen, TLS-/JWT-Fehler, Bindungs-Ereignisse, Skript-Fehler. Eintraege sind nach Datum, Uhrzeit und Host (IP oder Account-Name) sortiert. Das Protokoll ist die erste Anlaufstelle bei Stoerungen.
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.


==Statistik==
==Statistik==


Die Tabelle '''RESTSRV_STATS''' enthaelt eine Statistik aller bearbeiteten Anfragen mit Zugang, Endpunkt, Methode, HTTP-Status und Laufzeit in Millisekunden. Aufruf der 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 Endpunkt-Liste: F8 zeigt die Statistik des markierten Endpunkts.
* Aus der Zugaenge-Liste: F8 zeigt die Statistik des markierten Zugangs.
* Aus der Zugänge-Liste: F8 zeigt die Statistik des markierten Zugangs.


==Konsole==
==Konsole==
Zeile 105: Zeile 105:
|}
|}


Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Eintraege landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.
Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.


==Weiterfuehrende Seiten==
==Weiterführende Seiten==


* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-fuer-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Server|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugaenge]] - API-Keys, JWT, CORS, Host-Beschraenkung
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] - API-Keys, JWT, CORS, Host-Beschränkung
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel: Datensatz anlegen mit JSON-Body]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel: Datensatz anlegen mit JSON-Body]]

Version vom 19. Mai 2026, 07:05 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


REST-Server

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

Der OBS REST-Server stellt einen frei konfigurierbaren HTTP/HTTPS-Dienst bereit, über den externe Teilnehmer auf Funktionen und Daten der OBS-Datenbank zugreifen können. Jeder Endpunkt wird über ein in OBS gepflegtes Pascal-Script bedient, die Rückgaben erfolgen ausschliesslich im JSON-Format.

Aufruf des Moduls in OBS: Stammdaten -> Z Weitere Stammdaten -> REST-Server

Anwendungsbereiche

Typische Einsatzfälle:

  • Bereitstellung von OBS-Daten für Webseiten (Steürungsdaten, Statistiken, Verfügbarkeiten)
  • Anbindung mobiler Endgeräte (Zeiterfassung, QR-Scanner, Lagerlisten)
  • Integration mit Drittsystemen (ERP, Shop, Buchhaltung) über JSON-APIs
  • Empfang von WebHook-Aufrufen externer Dienste (z.B. Bezahl-Callbacks)
  • Bereitstellung interner Microservices mit gegenseitiger Authentifizierung (mTLS)

Architektur im Überblick

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

Baustein Tabelle Zweck
Server RESTSRV_SERVER TLS-Profil + eigene HTTP-Server-Instanz, kann mehrfach existieren
Bindung RESTSRV_BINDINGS IP-Adresse + Port pro Server
Zugang RESTSRV_ACCOUNT API-Key, optionale Host- und CORS-Beschränkung, optionale JWT-Konfiguration
Endpunkt RESTSRV_ENDPOINTS Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
Berechtigung RESTSRV_ACCESS Verbindet Zugang und Endpunkt
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:

  1. Rate-Limit-Prüfung (pro IP und global)
  2. Authentifizierung über den API-Key (Header apikey)
  3. CORS-Prüfung (sofern Origin-Header gesetzt)
  4. Optional: JWT-Prüfung (sofern für den Zugang aktiviert)
  5. Auflösung von Endpunkt / Sub-URL / Version
  6. Prüfung der Berechtigung (Zugang -> Endpunkt)
  7. Ausführung des Endpunkt-Skripts (oder WebHook-Antwort)
  8. JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag

Adressierung

Ein Endpunkt wird über drei Bestandteile angesprochen: Endpunkt-Name, optionale Sub-URL und Version: 

http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]

Beispiele: 

https://api.meinserver.de/kalender/v1
https://api.meinserver.de/email/mein_konto/v1.0
https://api.meinserver.de/zeiterfa/mobile/v2

Durch die Versionierung kann eine Endpunkt-Funktionalität verändert werden, ohne bestehende Konsumenten zu brechen.

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

Sicherheitsmerkmale

Der REST-Server enthält eine Reihe fest verdrahteter Schutzmechanismen:

  • Rate-Limit: max. 10 fehlgeschlagene und 120 erfolgreiche Anfragen pro IP und 60 Sekunden, max. 600 Anfragen global pro 60 Sekunden. Beim Überschreiten wird HTTP 429 zurückgegeben.
  • Body-Limit: max. 10 MB Request-Body, max. 1024 Zeichen pro Header- oder Query-Parameter.
  • 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.

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:

Befehl Wirkung
show <n> Zeigt die Details zum Debug-Eintrag #n (z.B. Request-Header, Response-Body), JSON wird farbig formatiert
exit / quit Beendet den Server geordnet

Im Service-Modus (Windows-Dienst) ist die Konsole nicht sichtbar. Alle Einträge landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.

Weiterführende Seiten

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