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-Schnittstelle=
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss ueber den OBS-Support aktiviert werden.}}
Über diesen OBS-Dienst wird ein Zugriff auf beliebige Daten und Funktionen durch externe Teilnehmer ermöglicht.


Menü unter '''Stammdaten''' -> '''Z Weitere Stammdaten''' -> '''REST-Server'''
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.


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


Ein Endpunkt besteht aus Name, Sub-URL und Version, wobei die SUB-URL optional ist. Die Kombination dieser drei Werte definiert die Adresse über die der Endpunkt erreichbar ist:
==Anwendungsbereiche==


http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]<br />
Typische Einsatzfaelle:
Beispiele:<br />
http://www.meinserver.de/kalender/v1<br />
http://www.meinserver.de/email/mein_konto/v1.0<br />


Durch die Versionierung der Endpunkte kann eine Funktionalität geändert werden, ohne dabei den Zugriff für Konsumenten der alten Version einzuschränken. Das ist immer dann sinnvoll, wenn es viele verschiedene Konsumenmten gibt, die nicht parallel zur Änderung des Endpunktes mit angepasst werden können.
* Bereitstellung von OBS-Daten fuer Webseiten (Steuerungsdaten, Statistiken, Verfuegbarkeiten)
* Anbindung mobiler Endgeraete (Zeiterfassung, QR-Scanner, Lagerlisten)
* Integration mit Drittsystemen (ERP, Shop, Buchhaltung) ueber JSON-APIs
* Empfang von WebHook-Aufrufen externer Dienste (z.B. Bezahl-Callbacks)
* Bereitstellung interner Microservices mit gegenseitiger Authentifizierung (mTLS)


=Zugänge / Authentifizierung=
==Architektur im Ueberblick==


Der Zugriff auf den REST-Dienst wird über Zugänge ermöglicht. Ein Zugang hat einen Namen zur Identifizierung (wird auch im Protokoll so angezeigt) und einen API-Key.
Der REST-Server besteht aus mehreren aufeinander aufbauenden Bausteinen, die alle in OBS gepflegt werden:
Der API-Key ist ein eindeutiger Schlüssel der dem Konsumenten bekannt sein muss, damit er auf eine Ressource zugreifen darf.


Zur Sicherheit kann noch ein Hostname vergeben werden. Der Zugang kann dann ausschließlich über diesen Hostnamen verwendet werden. Diese Option sollte, soweit möglich, immer genutzt werden.
{| class="wikitable"
! 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-Beschraenkung, 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-Eintraege
|-
| Statistik    || RESTSRV_STATS        || Aufrufzaehler, Antwortzeiten und HTTP-Status pro Endpunkt
|}


==Berechtigung / Authorisierung==
Eine Anfrage durchlaeuft folgende Stationen:


Damit ein Endpunkt über einen Zugang erreicht werden kann, muss erst die dafür nötige Berechtigung vergeben werden. Die Berechtigungen für einen Endpunkt werden über F6 in der Endpunkt-Liste verwaltet.
# Rate-Limit-Pruefung (pro IP und global)
# Authentifizierung ueber den API-Key (Header ''apikey'')
# CORS-Pruefung (sofern ''Origin''-Header gesetzt)
# Optional: JWT-Pruefung (sofern fuer den Zugang aktiviert)
# Aufloesung von Endpunkt / Sub-URL / Version
# Pruefung der Berechtigung (Zugang -> Endpunkt)
# Ausfuehrung des Endpunkt-Skripts (oder WebHook-Antwort)
# JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag


=Bindungen=
==Adressierung==


Hier werden die Netzwerkbindungen definiert, über die der REST-Dienst verfügbar sein soll. Das ist i.d.R. die interne IP des Servers auf dem der REST-Dienst betrieben wird.
Ein Endpunkt wird ueber drei Bestandteile angesprochen: Endpunkt-Name, optionale Sub-URL und Version:


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


Protokollierung aller Zugriffe und Fehler
Beispiele:


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


Statistiken über Zugriffe und Zugriffszeiten
Durch die Versionierung kann eine Endpunkt-Funktionalitaet veraendert werden, ohne bestehende Konsumenten zu brechen.
 
==Unterstuetzte 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]].
 
==Sicherheitsmerkmale==
 
Der REST-Server enthaelt 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.
* '''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 Praefix:''' Parameter-Namen mit Praefix ''_OBS_'' koennen von aussen nicht gesetzt werden, sie sind fuer 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 faehrt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur fuer ein dediziertes Debug-Profil moeglich.
* '''mTLS''' (Mutual TLS): erzwingt, dass jeder Client ein gueltiges 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.
 
==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.
 
==Statistik==
 
Die Tabelle '''RESTSRV_STATS''' enthaelt 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 Zugaenge-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"
! 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 Eintraege landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.
 
==Weiterfuehrende Seiten==
 
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-fuer-Schritt-Anleitung
* [[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/Endpunkte|Endpunkte]] - Verwaltung, Berechtigungen, WebHooks
* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel: Datensatz anlegen mit JSON-Body]]

Version vom 19. Mai 2026, 06:38 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 ueber 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.

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

Anwendungsbereiche

Typische Einsatzfaelle:

  • Bereitstellung von OBS-Daten fuer Webseiten (Steuerungsdaten, Statistiken, Verfuegbarkeiten)
  • Anbindung mobiler Endgeraete (Zeiterfassung, QR-Scanner, Lagerlisten)
  • Integration mit Drittsystemen (ERP, Shop, Buchhaltung) ueber JSON-APIs
  • Empfang von WebHook-Aufrufen externer Dienste (z.B. Bezahl-Callbacks)
  • Bereitstellung interner Microservices mit gegenseitiger Authentifizierung (mTLS)

Architektur im Ueberblick

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-Beschraenkung, 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-Eintraege
Statistik RESTSRV_STATS Aufrufzaehler, Antwortzeiten und HTTP-Status pro Endpunkt

Eine Anfrage durchlaeuft folgende Stationen:

  1. Rate-Limit-Pruefung (pro IP und global)
  2. Authentifizierung ueber den API-Key (Header apikey)
  3. CORS-Pruefung (sofern Origin-Header gesetzt)
  4. Optional: JWT-Pruefung (sofern fuer den Zugang aktiviert)
  5. Aufloesung von Endpunkt / Sub-URL / Version
  6. Pruefung der Berechtigung (Zugang -> Endpunkt)
  7. Ausfuehrung des Endpunkt-Skripts (oder WebHook-Antwort)
  8. JSON-Antwort, Statistik-Eintrag, Protokoll-Eintrag

Adressierung

Ein Endpunkt wird ueber 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-Funktionalitaet veraendert werden, ohne bestehende Konsumenten zu brechen.

Unterstuetzte 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 enthaelt 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.
  • 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 Praefix: Parameter-Namen mit Praefix _OBS_ koennen von aussen nicht gesetzt werden, sie sind fuer 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 faehrt der Server ohne Zertifikat und Key nicht hoch. Plain-HTTP ist nur fuer ein dediziertes Debug-Profil moeglich.
  • mTLS (Mutual TLS): erzwingt, dass jeder Client ein gueltiges 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.

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.

Statistik

Die Tabelle RESTSRV_STATS enthaelt 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 Zugaenge-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 Eintraege landen dort ausschliesslich in der Tabelle RESTSRV_PROTO.

Weiterfuehrende Seiten

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