OBS Wiki - Benutzerbeiträge [de]

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-11-05T12:40:03Z

MINERVA-Rademacker: Zugangscode fuer die OBS-Smart-App mit F6 ergaenzt [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Ein Wildcard-Zugang eignet
sich deshalb für Artefakte, die für jeden bestimmt sind (Test-APK, Handbuch),
'''nicht''' für Kundenbelege. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].}}

{{Hinweis|Bei einem Wildcard-Zugang sollte ''CORS-Origin'' '''leer''' bleiben.
Ein ''*'' dort wirkt auf die Preflight-Antwort '''aller''' Zugänge (siehe unten);
ein Download über die Adresszeile des Browsers sendet ohnehin kein ''Origin'',
CORS greift dort also gar nicht.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

{{Hinweis|Hinter einem Reverse-Proxy ist die Remote-IP immer die des Proxys. Die Host-Beschränkung kann dort keine einzelnen Konsumenten unterscheiden. Der Header ''X-Forwarded-For'' wird dafür bewusst nicht ausgewertet, weil jeder Client ihn selbst setzen kann.}}

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.firma.de;https://test.firma.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

{{Achtung|Die Lebensdauer eines Refresh-Tokens ist nach oben auf '''372 Tage'''
begrenzt. Ein mit ''_OBS_JWT_REFRESH_EXP'' länger ausgestelltes Token wird bei der
Vorlage '''nicht mehr verifiziert''' und mit 401 abgewiesen - der Fehler fällt
also erst Monate später auf, beim ersten Erneuerungsversuch.}}

Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''', dem Code ''AUTH_FAILED'' und reicht den Text aus dem Feld
''error'' als ''error.message'' an den Client durch - der Konsument kann ihn also
direkt anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|''AUTH_FAILED'' unterscheidet die '''abgelehnte Anmeldung''' vom
''AUTH_EXPIRED'', das ein abgelaufenes oder gesperrtes Token liefert. Ein Client
sollte auf den Code reagieren und nicht auf den Text: Bei ''AUTH_FAILED'' gehört
die Anmeldemaske noch einmal vorgelegt, bei ''AUTH_EXPIRED'' erst ein Refresh
versucht.}}

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('all');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Woher ein Anmelder seine Identität bekommt==

'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.

Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.

Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt". Schickt ein Reverse-Proxy den Header
''X-Forwarded-For'' mit, steht dessen Wert zusätzlich in ''rt_ip_fwd''; ''rt_ip'' bleibt
die IP-Adresse der Verbindung.

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Firma GmbH/CN=client-prod.firma.de
/C=DE/O=Firma GmbH/CN=client-test.firma.de

Mit '''CN=client-prod.firma.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Firma GmbH;CN=client-prod.firma.de''.

==Zugangscode für die App==

Ein Gerät mit einer OBS-Smart-App braucht drei Angaben: die Adresse des REST-Servers, den API-Key des Zugangs und - in internen Netzen - den Zertifikats-Pin. OBS fasst sie zu einem '''Zugangscode''' zusammen, den die App als QR-Code einliest.

Markieren Sie den Zugang in der Liste und drücken Sie {{F6}}. Der Dialog belegt alle Felder aus der vorhandenen Einrichtung vor; überschreiben können Sie jedes davon.

{| class="wikitable"
! Feld !! Woher der Vorschlag kommt
|-
| '''App''' || Erstes Segment des Endpunkt-Pfades, zum Beispiel ''service''. Sind dem Zugang Endpunkte mehrerer Apps zugeordnet, weist der Dialog darauf hin
|-
| '''Host (FQDN)''' || Zertifikatsname des Server-Profils. Hier gehört die Adresse hinein, unter der das '''Gerät''' den Server erreicht - nicht die, auf der der Dienst lauscht
|-
| '''Port''' || Standard-Bindung des Server-Profils, sonst die erste aktive
|-
| '''HTTPS''' || Aus dem Server-Profil
|-
| '''Anzeigename''' || Name des Zugangs. Er erscheint in der App als Bezeichnung der Verbindung
|-
| '''API-Key''' || Der API-Key des Zugangs
|-
| '''Zertifikats-Pin''' || Nur, wenn das Server-Profil einen führt, siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Eigenes Zertifikat und Pin|Eigenes Zertifikat und Pin]]
|-
| '''Alter Key noch Tage''' || Nur beim Schlüsseltausch: wie lange der bisherige API-Key daneben gültig bleibt
|}

Unter '''Hinweise''' sammelt der Dialog, was fehlt oder fragwürdig ist - etwa ein Host, der auf den Server selbst zeigt und vom Gerät aus nicht erreichbar wäre. Solange eine Pflichtangabe fehlt, entsteht kein Code.

===Tasten im Dialog===

{| class="wikitable"
! Taste !! Funktion
|-
| {{F2}} || QR-Code anzeigen, zum Abfotografieren mit dem Gerät
|-
| {{F3}} || Schlüssel tauschen: OBS erzeugt einen neuen API-Key. Der bisherige bleibt so viele Tage gültig, wie unter '''Alter Key noch Tage''' eingetragen sind - in dieser Zeit lesen die Geräte den neuen Code ein, ohne dass der Betrieb steht
|-
| {{F4}} || Zugangscode in die Zwischenablage
|-
| {{Key|Esc}} || Dialog schliessen
|}

{{Achtung|Der Zugangscode enthält den API-Key im Klartext. Geben Sie ihn nur an das Gerät weiter, für das er bestimmt ist, und verschicken Sie ihn nicht über offene Kanäle.}}

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F6''' - Zugangscode für eine OBS-Smart-App
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung

2026-11-05T12:40:03Z

MINERVA-Rademacker: Eigenes Zertifikat als dritter Weg; Pin als Voraussetzung ausgeschlossen [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Zertifikatserneuerung =

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

{{Hinweis|Jedes Server-Profil braucht im Betrieb ein Zertifikat, auch hinter einem Reverse-Proxy und im VPN: Eine App verbindet sich ausschliesslich per HTTPS, und ohne Zertifikat startet das Profil nicht. ''kein SSL'' ist nur für lokale Tests gedacht. Das Zertifikat beziehen Sie entweder automatisch wie hier beschrieben, oder Sie hinterlegen es von Hand im Server-Profil und tauschen es vor Ablauf. In einem internen Netz ohne eigene Domain stellt OBS auf Wunsch selbst eines aus, siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Eigenes Zertifikat und Pin|Eigenes Zertifikat und Pin]].}}

{{Auf einen Blick|1=
* '''Zwei Prüfarten.''' http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
* '''Selbsttest vorab.''' Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
* '''Erneuerung ab 30 Tagen Restlaufzeit.''' Das bisherige Zertifikat bleibt als Rückfall erhalten.
* '''dns-01 braucht nur ausgehende Verbindungen''' und eignet sich damit für VPN und für Server ohne Portfreigabe.
}}

== Voraussetzungen ==
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.firma.de''. Platzhalter-Zertifikate (''*.firma.de'') werden nicht unterstützt.
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL''' und ohne Haken '''Eigenes Zertifikat (Pin)''' - der Pin und die automatische Erneuerung schliessen sich aus, weil jede Erneuerung einen neuen Schlüssel und damit einen neuen Pin erzeugt.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>).
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

=== Welche Prüfart? ===
{| class="wikitable"
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss
|-
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist || Port 80
|-
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts
|}

Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|öffentlichen Freigabe]] passt:
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy. Der REST-Server braucht trotzdem ein Zertifikat für die Strecke vom Proxy. Dafür genügt ein selbst signiertes Zertifikat oder eines Ihrer internen Zertifizierungsstelle, sofern der Proxy ihm vertraut. Es wird im Server-Profil hinterlegt und muss vor Ablauf getauscht werden.
* '''VPN:''' dns-01.

=== Wege bei dns-01 ===
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag <code>_acme-challenge.<Name></code> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

{| class="wikitable"
! Weg !! Wann !! Einmalig beim DNS des Namens !! Einstellung '''DNS-Anbieter'''
|-
| Direkt beim Anbieter || Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS || nichts, Sie brauchen nur ein API-Token || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf eine Zone bei einem Anbieter || Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen || CNAME <code>_acme-challenge.<Name></code> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf acme-dns || Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister || CNAME <code>_acme-challenge.<Name></code> auf die ''fulldomain'' des acme-dns-Kontos || ''acme-dns''
|}

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

{{Hinweis|Nutzen Sie einen DNS-Anbieter, der hier nicht aufgeführt ist, wenden Sie sich an den OBS-Support. Bietet der Anbieter eine Schnittstelle (API) für DNS-Einträge, ist eine Anbindung in der Regel möglich. Bis dahin funktioniert der CNAME-Weg mit jedem Anbieter.}}

{{Hinweis|Namen von DynDNS-Diensten (zum Beispiel ''…myfritz.net'') eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.}}

== Vorgehen ==
=== Gemeinsame Einstellungen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server → Server''' und öffnen Sie das Server-Profil.
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''.
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll.
# Tragen Sie unter '''Kontakt bei der CA''' eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
# Richten Sie die Registerkarte '''5 DNS-Prüfung''' nach einem der folgenden Abschnitte ein und speichern Sie.
# Starten Sie den REST-Dienst neu.
}}

=== Prüfart http-01 ===
{{Schritte|1=
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
# Leiten Sie am Router Port 80 von aussen auf den Server des REST-Dienstes weiter.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer.
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein.
}}

Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

=== Prüfart dns-01 direkt beim DNS-Anbieter ===
{{Schritte|1=
# Erstellen Sie beim Anbieter der Zone ein API-Token:
#* '''Hetzner:''' ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
#* '''Cloudflare:''' ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
#* '''IONOS:''' einen API-Schlüssel. Er besteht aus Präfix und Secret.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''dns-01 (DNS-Eintrag)'' und im Feld '''DNS-Anbieter''' den Anbieter.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein, bei IONOS in der Form <code>Präfix.Secret</code>.
# Lassen Sie '''Name des TXT-Eintrags''' leer.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter ===
{{Schritte|1=
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs-firma.acme.example.de''. Einen Eintrag müssen Sie dort nicht anlegen.
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.firma.de</code> auf ''obs-firma.acme.example.de''.
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein.
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs-firma.acme.example.de''.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf acme-dns ===
{{Schritte|1=
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den DNS-Anbieter ''acme-dns''.
# Tragen Sie unter '''Adresse (acme-dns)''' die Adresse der Instanz ein. Sie beginnt mit <code>https://</code>.
# Lassen Sie '''Benutzer (acme-dns)''', '''Schlüssel / API-Token''' und '''Name des TXT-Eintrags''' leer und speichern Sie.
# Geben Sie in der Konsole <code>cert test</code> ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter '''Letzte Meldung''' steht danach der CNAME, den Sie anlegen müssen.
# Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: <code>_acme-challenge.<Name></code> auf die genannte ''fulldomain''.
# Geben Sie in der Konsole erneut <code>cert test</code> ein.
}}

{{Achtung|Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen ''fulldomain'' anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.}}

=== Erstes Zertifikat holen ===
Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

=== Testbetrieb ===
{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

== Ergebnis ==
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Unter '''Letzte Meldung''' steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt '''Zertifikat gültig bis''' das Ablaufdatum, und <code>cert</code> in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht.
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld '''Gesperrt bis''' zeigt, bis wann. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre.

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

== Wenn es nicht klappt ==
Die Meldungen stehen unter '''Letzte Meldung''' und im Protokoll des REST-Servers.

{| class="wikitable"
! Meldung !! Ursache
|-
| "Port 80 laesst sich nicht oeffnen - er ist belegt" || Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
|-
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt
|-
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer
|-
| "acme-dns: Konto unvollstaendig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
|-
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
|-
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben
|-
| "IONOS: keine Zone zu … im Vertrag des Schluessels" || Der API-Schlüssel gehört zu einem anderen Vertrag
|-
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern
|-
| "… ist nach 210 Sekunden noch nicht ueberall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus
|-
| "kein oeffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
|-
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein
|}

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Automatische Zertifikatserneuerung|Server-Profile: Felder der Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-11-05T12:40:02Z

MINERVA-Rademacker: Vorlage:-Praefix; Quelltext-Dateiname aus dem Hinweis entfernt [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige '''Prozedur''' implementiert. Der Server ruft genau die Prozedur auf, die zur Methode des eingehenden Requests passt.

procedure Get (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);

Zwei Handles, kein Rückgabewert: '''oReader''' ist die Anfrage, '''oWriter''' die
Antwort. Beide erzeugt der Server, beide gehören ihm - im Skript wird nichts
angelegt und nichts freigegeben.

{{Achtung|'''DELETE hat keine Skript-Methode.''' <code>Delete</code> ist in der
Skriptsprache eine Standardprozedur (Löschen aus einer Zeichenkette); eine eigene
Prozedur dieses Namens lässt sich nicht übersetzen, und der Fehler nennt nur die
Zeile der Deklaration. Wer einen DELETE-Endpunkt braucht, legt die Methode unter
einem anderen Verb ab oder trennt sie in ein eigenes Skript.}}

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Prozedur. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Die Anfrage lesen: oReader==

''oReader'' ist der einzige Zugang zur Anfrage - Query, Header, Formularfelder,
Pfadwerte, Token-Claims und Körper. Alles davon sind '''Zeichenketten''' oder
werden über einen typisierten Leser geholt.

{| class="wikitable"
! Aufruf !! Was er liefert
|-
| <code>oReader.Param('kundennr')</code> || Query-Parameter, POST-Parameter (form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet
|-
| <code>oReader.Path('uid')</code> || Wert eines Platzhalters aus dem Pfad-Template
|-
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung
|-
| <code>oReader.Claim('tenant')</code> || Custom-Claim des vorgelegten Tokens
|-
| <code>oReader.Subject()</code> || Subject des Tokens (''sub''-Claim)
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests
|-
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+02:00''
|-
| <code>oReader.HasBody()</code> || Wurde überhaupt ein JSON-Körper gesendet?
|}

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Werte, die von aussen kommen, können die reservierten Namen nicht besetzen.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
// ...
end;

===Der Körper: Zugriff über Pfade===

Den JSON-Körper liest ''oReader'' über '''Pfade'''. Es gibt keine Unterobjekte im
Skript, keinen Cast, kein ''.Items[i]'' - und damit auch keine Lebensdauer, um die
sich jemand kümmern müsste.

{| class="wikitable"
! Aufruf !! Bedeutung
|-
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': war das Feld da? Fehlt es, bleibt die Variable unverändert
|-
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl
|-
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. '''Der Dezimalpunkt aus JSON wird richtig gelesen''' - kein ''StrTran'' mehr
|-
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean
|-
| <code>oReader.NumDef('rabatt', nWert, 0)</code> || wie ''Num'', mit Vorgabewert
|-
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden? (auch bei ''null'')
|-
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste
|-
| <code>oReader.IsArr('zeiten')</code> / <code>IsObj('zeiten[0]')</code> || Gestalt prüfen
|-
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst
|}

'''Verschachtelung steht im Pfad''' - Punkt für Felder, eckige Klammern für Listen:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cVon : string;
nAnz : Integer;
nI : Integer;
begin
nAnz := oReader.Count('zeiten');
for nI := 0 to nAnz - 1 do begin
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
// ... cVon verarbeiten ...
end;
end;
end;
</syntaxhighlight>

{{Hinweis|'''Der Rückgabewert unterscheidet „nicht gesendet" von „leer
gesendet".''' <code>oReader.Str('feld', cWert)</code> liefert bei
<code>"feld": null</code> ''true'' mit leerem Wert und bei fehlendem Feld
''false''. Genau diese Unterscheidung braucht ein PATCH-artiger Aufruf: „Feld
löschen" und „Feld nicht anfassen" sehen sonst gleich aus.}}

Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und
''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB - bei einem gepackt gesendeten Körper zusätzlich das 400fache der gesendeten Grösse, siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression. Beide Überschreitungen beantwortet der Server mit '''413''', das Skript läuft gar nicht erst an.

===Werte des Servers===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims über den Reader zur
Verfügung. Sie tragen intern weiterhin die Namen mit Präfix '''_OBS_''' - im
Skript werden sie aber über die Zugriffe der Tabelle oben gelesen und nicht mehr
über den Namen:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_JWT_ID')</code> || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| <code>oReader.Subject()</code> || Subject (''sub''-Claim) - typisch Benutzername
|-
| <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| <code>oReader.Claim('tenant')</code> || Beliebiger Custom-Claim des Tokens, hier ''tenant''; im Folge-Skript lesbar
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+02:00''. Er geht in die Zeitfunktionen (siehe [[#Zeitangaben auf der Leitung|Zeitangaben]])
|-
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''oReader.Claim('sid')'' und ''oReader.Claim('rid')'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit einem eigenen Claim ''sid''
nicht überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte über ''oReader.Path'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || <code>oReader.Path('uid')</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>oReader.Path('uid')</code>, <code>oReader.Path('code')</code>
|}

Diese Werte kommen aus dem Routing und sind durch den Client nicht fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über den Reader. Das
Skript entscheidet selbst über die weitere Verarbeitung (z.B. DMS-Ablage). Der
Body wird in diesem Fall '''nicht''' als JSON geparst - ''oReader.HasBody()'' ist
''false''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

'''Wie die Datei übertragen wurde, spielt für das Skript keine Rolle.''' Beide
Wege - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dieselben vier Werte. Das
Übertragungsprotokoll samt Header, Statuscodes und Resume-Verhalten steht in
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| <code>oReader.UploadName()</code> || Originaldateiname
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt), kleingeschrieben
|-
| <code>oReader.UploadSha()</code> || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''UploadPath()'' und ''UploadName()'' gefüllt
sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

Zusatzangaben, die im selben Aufruf mitkommen, liest das Skript mit
<code>oReader.Form('<name>')</code> - bei <code>multipart/form-data</code> sind
das die Partien ohne <code>filename=</code>. Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

==Die Antwort schreiben: oWriter==

Der Writer schreibt '''sequentiell''': jeder Aufruf hängt ein Feld an, an der
Stelle, an der er steht. Die äussere Klammer der Antwort setzt der Server. Wird
nichts geschrieben, antwortet er mit ''{}''. Content-Type ist
''application/json; charset=utf-8'', der Status 200, sofern das Skript nichts
anderes setzt.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
oWriter.Str('wert_string', '123');
oWriter.Int('wert_int' , 456);
end;
</syntaxhighlight>

{| class="wikitable"
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
| <code>oWriter.StrN('name', cWert)</code> || wie ''Str'', aber '''null''' statt einer leeren Zeichenkette
|-
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. '''Immer mit Dezimalpunkt''', unabhängig von der Locale des Servers
|-
| <code>oWriter.Bool('aktiv', lWert)</code> || ''true'' / ''false''
|-
| <code>oWriter.Null('lat')</code> || ausdrücklich ''null''
|-
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
| <code>oWriter.RootArr()</code> || Die '''Wurzel''' ist eine Liste statt eines Objekts. Muss vor dem ersten Feld stehen; ein ''ArrEnd'' gibt es dazu nicht
|-
| <code>oWriter.Raw('meta', cJson')</code> || Fertiges JSON-Fragment einbetten. Siehe unten
|}

'''In einer Liste hat ein Eintrag keinen Namen''' - der leere Feldname ist genau
das:

<syntaxhighlight lang="pascal" line>
oWriter.ArrBegin('dateien');
while (not q.EoF) do begin
oWriter.ObjBegin('');
oWriter.Str ('uid' , q.A2C('f_uid'));
oWriter.Int ('bytes' , q.A2I('f_bytes'));
oWriter.StrN('kategorie', AllTrim(q.A2C('f_kat'))); // null wenn leer
oWriter.ObjEnd;
q.Next();
end;
oWriter.ArrEnd;
</syntaxhighlight>

Ein Name in einer Liste und ein fehlender Name in einem Objekt sind beides
'''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die
Stelle im Protokoll - er liefert kein halbes JSON aus. Dasselbe gilt für einen
Stapel, der am Ende der Methode noch offen ist.

{{Hinweis|'''Ein Helfer bekommt den Writer als Parameter''' und schreibt an der
Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurück. Damit
steht die Reihenfolge der Antwort im Code und nicht im Zusammenbau:

<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}

'''Raw ist der Notausgang und prüft.''' Er parst das Fragment und bettet den
'''Originaltext''' ein; ungültiges JSON gibt einen Serverfehler, der das Feld
nennt. Gebraucht wird er für ein gespeichertes, '''signiertes''' Dokument:
Parsen und Neuserialisieren würde die signierte Feldreihenfolge zerstören.

===Zeitangaben auf der Leitung===

Zeitstempel gehen als '''ISO-8601 mit Offset''' über die Leitung. Die Wandlung
gehört nicht ins Skript - dort saß der Fehler „zwei Stunden zu früh" an drei
Stellen gleichzeitig:

{| class="wikitable"
! Aufruf !! Zweck
|-
| <code>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt -> ''2026-09-09T14:12:00+02:00''. Leerer String bei leerem Datum
|-
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette -> OBS-Zeitpunkt in '''Ortszeit des Servers'''
|-
| <code>oReader.Offset()</code> || Der Offset, der in beide hineingeht
|-
| <code>RestOffsetToMinutes(cOffset)</code> || Offset in Minuten, für eigene Rechnungen
|}

==Antwort steuern: Statuscode, Header, traceId==

Statuscode, Header und das Sperren einer Sitzung laufen über eigene Aufrufe des
Writers, '''nicht''' über Felder im Körper.

{| class="wikitable"
! Aufruf !! Wirkung
|-
| <code>oWriter.Status(201)</code> || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200
|-
| <code>oWriter.Header('ETag', '7')</code> || Beliebiger Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen und Werten werden entfernt (Schutz vor Header-Injection)
|-
| <code>oWriter.NoBody()</code> || Kein Körper - für '''204'''
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden
|-
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld „menge" fehlt')</code> || Fertige Fehlerantwort in der Form des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Statt eines JSON-Körpers eine '''Datei''' ausliefern. Die Datei bleibt liegen, der Download ist wiederaufsetzbar. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Wie <code>SendFile</code>, aber die Datei wird nach dem Senden '''gelöscht''' und der Download ist nicht wiederaufsetzbar - für Ergebnisse, die je Abruf entstehen (CSV-Export, Report)
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

Setzt ein Skript den Header '''Content-Encoding''' selbst - etwa weil es einen bereits gepackten Körper ausliefert -, hält sich die Engine heraus und packt die Antwort nicht noch einmal. Ohne diesen Header entscheidet der Server selbst, ob gzip zum Einsatz kommt.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueUid: string;
begin
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...

oWriter.Str('uid', cNeueUid);
oWriter.Status(201);
oWriter.Header('Location', '/v1/orders/' + cNeueUid);
oWriter.Header('ETag' , '1');
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var nMenge: Integer;
begin
if (not oReader.Int('menge', nMenge)) then begin
// Statuscode, code, message, uid und traceId in EINEM Aufruf - dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
nIfMatch: Integer;
begin
nAktuell := AuftragVersion(oReader.Path('uid'));
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geaendert');
exit;
end;

// ... speichern, Version hochzählen ...
oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Bei ''POST''/''PUT''/''PATCH''/''DELETE'' fängt der '''Server''' doppelte
Sendungen über den Header <code>Idempotency-Key</code> ab. Das Skript braucht dafür
'''keine eigene Logik''' - keine Schlüssel-Tabelle, keine Prüfung am Anfang der
Methode.

{{Hinweis|Der Header ist bei diesen vier Verben '''Pflicht'''. Fehlt er, antwortet
der Server mit '''400''' <code>IDEMPOTENCY_KEY_MISSING</code> - das Skript läuft
dann gar nicht erst an, es muss den Fall also auch nicht behandeln.}}

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''2xx''' mit ''SendFile''/''SendTempFile'' || '''Nichts''' wird gespeichert - eine Dateiantwort liesse sich nicht wiedergeben. Der Schlüssel wird freigegeben und ist danach wieder benutzbar
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel wird ebenfalls '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden
|}

{{Achtung|'''Das 5xx-Verhalten wurde am 25.08.2026 gedreht.''' Vorher blieb der
Schlüssel nach einem Serverfehler belegt - begründet mit „niemals eine
Doppelbuchung". Das war falsch gewichtet: der Vorgang wurde damit
'''unwiederholbar''', der Client bekam dauerhaft 503 und hätte die erfasste Arbeit
verwerfen müssen. Garantierter Datenverlust wiegt schwerer als ein möglicher
Doppelsatz.

'''Folge für die Auslegung:''' Ein schreibender Endpunkt sollte selbst
wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines
Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.}}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
// Eingangsdaten lesen
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;
</syntaxhighlight>

{{Hinweis|'''Im Anmeldeskript bleiben die _OBS_JWT_*-Felder Felder der
Antwort''' - anders als Status und Header, die zu Aufrufen des Writers geworden
sind. Der Grund: die Token-Ausstellung liest sie aus dem fertigen Körper, und
genau dort erwartet sie sie. Geschrieben werden sie deshalb wie jedes andere
Feld, nur eben mit dem Writer.}}

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als <code>oReader.Claim('<name>')</code>.
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''oReader.Claim(…)''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oReader.Param('_OBS_JWT_ID')'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und ruft dort ''oWriter.JwtRevoke''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
GeraeteRegistrierungLoeschen(oReader.Subject());

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('session');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Für einen spezifischen Fehler an den Konsumenten gibt es '''einen''' Aufruf. Er
baut dieselbe Hülle, die auch die Server-eigenen Fehler tragen - Statuscode,
''code'', ''message'', ''uid'' und ''traceId'' -, sodass beide Wege nicht
auseinanderlaufen können:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
if (Empty(oReader.Param('kundennr'))) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

{{Hinweis|'''Error verwirft einen schon begonnenen Körper''' und setzt seinen
eigenen. Ein Skript darf also getrost Felder schreiben und danach noch
abbrechen - was der Client sieht, ist die Fehlerantwort. Nur ein '''offener
Stapel''' (ein ''ObjBegin'' ohne ''ObjEnd'') bleibt auch dann ein Strukturfehler.}}

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

===Ändern: qSqlInit statt qSqlRead===

Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
benutzt - der Satz wird über <code>sys_uid</code> adressiert:

<syntaxhighlight lang="pascal" line>
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cSysUid); // Schreib-Index auf den Originalsatz
q.qSet('ti_status', '9');
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln, siehe unten
end;
qSqlFree(q);
</syntaxhighlight>

<code>qSqlRead</code> ist dafür die falsche Wahl, aus zwei Gründen:

* Es liest den '''kompletten Altsatz''' ein - ein zusätzlicher Lesezugriff, der Zeit kostet.
* Es schreibt anschliessend nur die '''Änderungen'''. Ist der neue Wert gleich dem alten, entsteht gar kein Write, und <code>SaveData</code> liefert '''False''' - ununterscheidbar von einem echten Fehlschlag.

{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen'''
Datensatz an, statt den vorhandenen zu ändern. Die <code>sys_uid</code> ist der
Schreib-Index und gehört bei jeder Änderung gesetzt.}}

Damit entfällt auch das übliche Paar aus <code>DB_LSeek</code> und
<code>qSqlRead</code>: '''eine''' Abfrage auf die <code>sys_uid</code> liefert
zugleich die Existenzprüfung und den Schreib-Index.

<syntaxhighlight lang="pascal" line>
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM tickets WHERE ' + cWhere + ' LIMIT 1', q)) then begin
if (not q.EoF) then begin
cUid := q.A2UID();
end;
end;
DB_Close(q);

if (not Empty(cUid)) then begin
// ändern: qSqlInit + sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
</syntaxhighlight>

===Mehrere Felder sind EIN Schreibvorgang===

Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:

<syntaxhighlight lang="pascal" line>
// FALSCH: fünf Felder, fünf Schreibvorgänge - und jeder Setzer, der sich
// seine sys_uid selbst holt, bringt zusätzlich eine eigene Abfrage mit
FeldSetzen(cUid, 'ti_status' , '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cUid);
q.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
q.qSet('ti_von' , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>

Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
sind '''nicht atomar'''. Bricht der dritte Schreibvorgang ab, steht die Zeile
halb geändert da - Grund gesetzt, Zeitpunkt nicht.

Wird nichts gesetzt, darf auch nicht geschrieben werden: das Schreibobjekt dann
mit <code>qSqlFree</code> freigeben, statt ein leeres <code>SaveData</code>
abzusetzen.

{{Hinweis|Ein Setzer für '''ein''' Feld (<code>FeldSetzen(cUid, cFeld, cWert)</code>)
ist bequem und deshalb verführerisch. Er versteckt aber je Aufruf eine eigene
Abfrage und ein eigenes <code>SaveData</code>. Für einen Vorgang mit mehreren
Feldern gehört ein '''Editier-Helfer''' her, der das Schreibobjekt liefert -
geschrieben wird einmal am Ende.}}

===Keine Abfrage je Zeile===

Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für
'''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein
einziges Feld. Der Ausweg ist immer derselbe:

* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen - bei einem '''eindeutigen''' Index auf dem Join-Feld kann er die Zeilen nicht vervielfachen.
* Einzelwerte aus einer 1:n-Beziehung über eine '''Unterabfrage''' in der SELECT-Liste holen, nicht über einen Join (der Join würde die Zeilen vervielfachen).
* Eine echte Unterliste (Positionen, Dateien) nur dann nachladen, wenn ein '''Zählfeld''' in der Hauptabfrage sagt, dass es überhaupt eine gibt.

{{Hinweis|Ein GET soll '''lesen'''. Schreibvorgänge im Lesepfad - etwas
"beim ersten Ausliefern festschreiben" - vervielfachen sich mit der Zeilenzahl
und treffen den Aufrufer, der nur eine Liste angefordert hat.}}

===Schreibfehler erkennen===

'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
Fehlermeldung, die es gibt.''' (Auch der '''Parameter''' ist ein Boolean:
''NEW_RECORD'' und ''UPDATE_RECORD'' sind Wahrheitswerte, keine Zahlen.) Schlägt das Schreiben in der Datenbank fehl
(''Duplicate entry'' auf einem eindeutigen Index, zu langer Wert, fehlende
Spalte), dann

* wird '''keine''' Exception ausgelöst,
* steht '''nichts''' in ''RESTSRV_PROTO'',
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.

Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Weil in einem Endpunkt schnell ein Dutzend Schreibvorgänge zusammenkommen, gehört
die Prüfung in eine eigene kleine Prozedur - am besten in die gemeinsame Lib:

<syntaxhighlight lang="pascal" line>
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := q.SaveData(lNeu);
qSqlFree(q); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;

// Aufruf statt SaveData + qSqlFree:
q := qSqlInit(oDB, 'tickets');
q.qSet('ti_betreff', cBetreff);
Speichern(q, NEW_RECORD, 'Ticket');
</syntaxhighlight>

Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
nach '''RESTSRV_PROTO''' und antwortet mit '''500'''. Liegt ein
''Idempotency-Key'' an, wird er dabei '''freigegeben''' - die Anfrage ist also
wiederholbar (siehe Abschnitt Idempotenz).

{{Hinweis|Ein fehlgeschlagenes Schreiben ist kein Fall, in dem ein Endpunkt
sinnvoll weiterlaufen kann: die Fachwirkung ist dann unvollständig. Wer trotzdem
weitermachen will - etwa weil mehrere unabhängige Sätze geschrieben werden -,
prüft den Rückgabewert und baut selbst eine Antwort. Ignorieren darf man ihn
nie.}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

===Wohin gehört welcher Code?===

Drei Ebenen, und die Zuordnung entscheidet, wie schnell eine Änderung wirkt:

{| class="wikitable"
! Art des Codes !! Wohin !! Wirksam
|-
| Fachlogik **einer** Anwendung - Feldnamen, Zustandswerte, Rollenregeln, Schreibziele || in die '''DWS-Lib dieser Anwendung''' (eigene Endpunkt-Zeile, per <code>{$L …}</code> eingebunden) || nach Ablauf des Cache-TTL, ohne Build
|-
| Mechanik, die '''mehrere''' Anwendungen brauchen - und auch das OBS-Umfeld || nach '''obs_lib''' als Delphi-Unit || erst nach Build und Rollout
|-
| Mechanik, die '''nur''' der REST-Server braucht || in die Units des Servers || erst nach Build und Rollout
|}

Die Regel hat einen praktischen Grund und keinen ästhetischen: Fachlogik ändert
sich in Tagen, Mechanik in Monaten. Was in der Lib liegt, ist nach einer Minute
aktiv; was in einer Unit liegt, braucht einen Build. Wer Fachlogik nach unten
schiebt, tauscht Geschwindigkeit gegen nichts ein.

{{Hinweis|Eine Anwendung, die ihre eigene Lib hat, kopiert sie '''nicht''' von
einer anderen. Zwei Kopien derselben Lib driften auseinander, und die Abweichung
fällt erst auf, wenn eine der beiden Anwendungen etwas Falsches tut. Geteiltes
gehört eine Ebene tiefer.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oReader.Str<T>(…)'' oder irgendein Generic || Generics gibt es in der Skriptsprache nicht. Die Leser sind je Typ eigene Methoden: ''Str'', ''Int'', ''Num'', ''Bool''
|-
| Eine eigene Prozedur ''Delete'' für DELETE || ''Delete'' ist eine '''Standardprozedur''' der Sprache. Die Deklaration lässt sich nicht übersetzen, und die Meldung nennt nur die Zeile - nicht die Ursache
|-
| Ein Helfer, der ein JSON-Fragment als String zurückgibt || Den '''Writer als Parameter''' übergeben und an der richtigen Stelle hineinschreiben. Fragmente von Hand zusammenzusetzen ist genau der Weg, auf dem die Reihenfolge und die Klammern verloren gingen
|-
| ''oWriter.ArrEnd'' nach ''RootArr'' || ''RootArr'' öffnet '''keine''' Ebene, es bestimmt nur die Klammer der Wurzel. Ein ''ArrEnd'' dazu ist ein Strukturfehler
|-
| Zahlen selbst formatieren (''NStr'', ''StrTran'') || <code>oWriter.Num('preis', nWert, 2)</code>. Selbst formatiert stand bei Werten ab 1000 der Tausendertrenner im JSON - gültiges JSON, falscher Wert, keine Meldung
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|-
| <code>q.SaveData(…)</code> als Anweisung schreiben || ''SaveData'' liefert einen '''Boolean'''. Ein SQL-Fehler beim Schreiben wirft '''keine''' Exception und landet in '''keinem''' Protokoll - der Rückgabewert ist die einzige Meldung. Immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Setzer-Aufruf || Ein <code>qSqlInit</code>-Objekt, beliebig viele <code>qSet</code>, '''ein''' <code>SaveData</code>. Einzeln geschrieben kostet jedes Feld eine eigene Abfrage samt eigenem Write - und der Vorgang ist nicht mehr atomar, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || In einer Liste sind das N Abfragen für eine Antwort. Über <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n) mitnehmen, siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skript-VM zum '''Absturz''' (Assertion in der Skript-VM), und zwar beim ersten '''Lesen''' des Werts - nicht schon beim Schreiben, die Ursache liegt also nicht dort, wo der Fehler auffällt. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und erst beim Aufrufer wandeln
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''lib_ScriptIO'' - Writer und Reader, siehe unten. '''System.JSON braucht ein Endpunkt-Skript nicht''' - der Writer erzeugt die Antwort, der Reader liest den Körper
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''
* ''lib_ScriptIO'' - ''TxRestWriter'', ''TxRestReader'' und die Zeitfunktionen ''RestIsoFromDate'' / ''RestDateFromIso'' / ''RestOffsetToMinutes''. Writer und Reader bekommt das Skript als Parameter; die Zeitfunktionen ruft es direkt

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>if (not q.SaveData(NEW_RECORD)) then …</code>, <code>qSqlFree(q)</code> – der Rückgabewert ist Pflicht, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Ändern || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('sys_uid', cUid)</code>, <code>q.qSet(…)</code>, <code>if (not q.SaveData(UPDATE_RECORD)) then …</code>, <code>qSqlFree(q)</code> – '''nicht''' <code>qSqlRead</code>, siehe [[#Ändern: qSqlInit statt qSqlRead|Ändern]]. Alle Felder derselben Zeile in '''ein''' Objekt, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[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]]

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-11-05T12:40:02Z

MINERVA-Rademacker: Zertifikats-Pin: zwei Felder, eigener Abschnitt und Validierung ergaenzt [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| zusätzliche Infos || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS-Modus aktiv || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Zertifikat (cert) || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Schlüssel (key) || PEM-Inhalt des privaten Schlüssels
|-
| Root-Zertifikat (ca) || PEM-Inhalt des CA-Zertifikats, gegen das '
|-
| Rate-Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Erfolgsanfragen || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Fehlanfragen || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Anfragen || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| max. Anfragen || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|-
| keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
|}

{{Hinweis|''max. Verbindungen'' und ''max. Anfragen'' sind die beiden
'''Lastgrenzen''' des Profils. Davon zu unterscheiden sind die festen Grenzen der
persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -,
die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe
[[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Persistente
Verbindungen.}}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Zertifikat + Schlüssel || Für den Betrieb, auch wenn der Server nur intern, hinter einem Reverse-Proxy oder per VPN erreichbar ist
|-
| '''mTLS''' || Zertifikat + Schlüssel + Root-Zert. || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein, mit ''Eigenes Zertifikat (Pin)'' stellt er sich selbst eines aus. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''HSTS:''' Jede Antwort eines TLS-Profils trägt ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse damit ein Jahr lang nur noch über HTTPS an. Beim Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
* '''Rotation:''' Bei '''automatischer Erneuerung''' tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus. Mit ''Eigenes Zertifikat (Pin)'' gibt OBS den Pin über den Zugangscode an die App weiter. Gepinnt wird der '''Schlüssel''', nicht das Zertifikat: Erneuern Sie das Zertifikat mit demselben Schlüssel, bleibt der Pin gleich und kein Gerät braucht einen neuen Zugangscode.
==Automatische Zertifikatserneuerung==

Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Prüfarten, Voraussetzungen, Einrichtung, Ablauf und Konsolenbefehle beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]].

===Felder===

Registerkarte '''4 Zertifikaterneuerung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Automatische Erneuerung || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = nur für Testsysteme, siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Testbetrieb|Testbetrieb]]
|-
| Zertifikatsname (FQDN) || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
|-
| Kontakt bei der CA || Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
|-
| Zertifikat gültig bis || Ablaufdatum des aktiven Zertifikats
|-
| Testzertifikat aus Staging || Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
|-
| Zustand || ''idle'' = nichts zu tun, ''pending'' = Vorgang läuft, ''error'' = letzter Versuch fehlgeschlagen
|-
| Letzte Meldung || Ergebnis des letzten Vorgangs - im Störungsfall das erste Feld, in das Sie sehen
|-
| Gesperrt bis || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
|-
| Letzter Selbsttest am || Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle
|-
| Selbsttest bestanden || Ergebnis dieser Prüfung
|-
| Eigenes Zertifikat (Pin) || Der Dienst stellt für dieses Profil ein eigenes Zertifikat aus, sobald Zertifikat und Schlüssel leer sind, und berechnet den zugehörigen Pin. Gedacht für interne Netze ohne eigene Domain, in denen keine Zertifizierungsstelle erreichbar ist. Nicht zusammen mit der automatischen Erneuerung
|-
| Zertifikats-Pin || Pin des Schlüssels, mit dem dieses Profil TLS spricht, in der Form <code>sha256/…</code>. Der Dienst berechnet ihn; die App erhält ihn über den Zugangscode und prüft damit jede Verbindung
|}

Die Felder von ''Zertifikat gültig bis'' bis ''Selbsttest bestanden'' sowie ''Zertifikats-Pin'' füllt der Dienst selbst; sie dienen der Anzeige.

Registerkarte '''5 DNS-Prüfung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Prüfart || ''http-01 (Port 80)'' oder ''dns-01 (DNS-Eintrag)'', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Welche Prüfart?|Welche Prüfart?]]
|-
| DNS-Anbieter || Nur dns-01: ''acme-dns'', ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| Adresse (acme-dns) || Nur acme-dns: Adresse der Instanz, beginnt mit <code>https://</code>
|-
| Benutzer (acme-dns) || Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an
|-
| Schlüssel / API-Token || acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form <code>Präfix.Secret</code>
|-
| Name des TXT-Eintrags || Leer = <code>_acme-challenge.<Zertifikatsname></code>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die ''fulldomain'' des Kontos
|}

{{Hinweis|Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.}}

==Eigenes Zertifikat und Pin==

In internen Netzen ohne eigene Domain ist keine Zertifizierungsstelle erreichbar, und ein von Hand erstelltes Zertifikat kennt keine App. Für diesen Fall setzen Sie den Haken '''Eigenes Zertifikat (Pin)''' und tragen unter '''Zertifikatsname (FQDN)''' die Adresse ein, unter der das Gerät den Server erreicht - auch eine IP-Adresse ist zulässig.

Beim nächsten Start des REST-Dienstes stellt der Dienst ein Zertifikat aus, sofern '''Zertifikat (cert)''' und '''Schlüssel (key)''' leer sind, und berechnet den Pin. Ein bereits hinterlegtes Zertifikat bleibt unangetastet - der Dienst füllt nur, was leer ist.

Den Pin gibt OBS zusammen mit Adresse und API-Key im Zugangscode an die App weiter. Die App vertraut dann genau diesem Schlüssel und keiner Zertifizierungsstelle; Name und Ablaufdatum des Zertifikats prüft sie nicht.

{{Achtung|Ein Wechsel des Schlüssels macht '''jeden bisher ausgegebenen Zugangscode ungültig''' - die Geräte kommen dann nicht mehr durch. Wollen Sie den Schlüssel wechseln, geben Sie vorher Zugangscodes mit altem und neuem Pin aus und stellen erst um, wenn alle Geräte den neuen Code haben. Das Ausstellen wiederholt der Dienst von sich aus nie: Solange ein Zertifikat hinterlegt ist, bleibt es stehen.}}

{{Hinweis|Der Pin und die automatische Erneuerung schliessen sich aus. Jede Erneuerung erzeugt einen neuen Schlüssel und damit einen neuen Pin; die Geräte wären danach ausgesperrt. OBS weist die Kombination beim Speichern zurück.}}

==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Dasselbe gilt hinter einem Reverse-Proxy: Alle Anfragen kommen dort von der IP-Adresse
des Proxys, und alle Konsumenten ohne API-Key teilen sich einen Zähler. Der Header
''X-Forwarded-For'' ändert daran nichts, er wird nur protokolliert.

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Immer geprüft wird:

* Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
* Nr und Name sind eindeutig.
* Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
* Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.
* ''Eigenes Zertifikat (Pin)'' ist weder zusammen mit der automatischen Erneuerung noch zusammen mit ''kein SSL'' gesetzt.

Nur bei '''aktivem''' Profil zusätzlich:

* Ohne ''kein SSL'', ohne automatische Erneuerung und ohne ''Eigenes Zertifikat (Pin)'' sind Zertifikat und Schlüssel vorhanden.
* Bei ''mTLS-Modus aktiv'' ist das Root-Zertifikat vorhanden.
* Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und ''kein SSL'' ist nicht gesetzt.
* Bei ''Eigenes Zertifikat (Pin)'' ist der Zertifikatsname vergeben, solange kein Zertifikat hinterlegt ist - der Dienst stellt das Zertifikat auf diesen Namen aus.

{{Hinweis|Ein '''nicht aktives''' Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.}}

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-11-05T12:39:59Z

MINERVA-Rademacker: Vorlage:-Praefix; Link ohne fuehrenden Schraegstrich korrigiert [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte liest das Endpunkt-Skript über
<code>oReader.Path</code>:

<syntaxhighlight lang="pascal">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
cUid := oReader.Path('uid'); // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Diese Werte stammen aus dem Routing und können nicht durch den Client
überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird. Das Skript liest Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>; bei <code>multipart/form-data</code> die übrigen Formularfelder über <code>oReader.Form('<name>')</code>.

'''Das Übertragungsprotokoll''' - Header, Statuscodes, Resume-Verhalten - steht auf einer eigenen Seite: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Datei-Downloads ==

Ein Endpunkt kann eine '''Datei''' statt eines JSON-Körpers zurückgeben -
PDF, CSV, eine APK. Dafür ist '''keine Freischaltung''' nötig: ein Download
entsteht dadurch, dass das Skript ihn mit <code>oWriter.SendFile(...)</code>
bzw. <code>oWriter.SendTempFile(...)</code> erzeugt, nicht dadurch, dass ein
Client ihn anfragt.

Content-Type, Dateiname, Bereichsanfragen (<code>Range</code>, '''206'''),
ETag und das Aufräumen temporärer Dateien übernimmt der Server. Einzelheiten:
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen.

{{Achtung|'''Ein Endpunkt besteht aus zwei Zeilen, und beide werden von Hand
gepflegt:''' der Eintrag in <code>RESTSRV_ENDPOINTS</code> und die Berechtigung
in <code>RESTSRV_ACCESS</code>. Fehlt die zweite, antwortet der Endpunkt
'''403''' - und sieht dabei fertig aus: Pfad, Skript und Server-Profil stehen
korrekt da, der Aufruf kommt trotzdem nicht durch. Das ist die häufigste Ursache
für ein „der Endpunkt ist doch angelegt" und kostet jedes Mal eine
Fehlersuche, weil der Statuscode nach einem Rechteproblem des Konsumenten
aussieht und nicht nach einer fehlenden Konfigurationszeile.

Beim Anlegen also '''immer beide Zeilen''', und beim Prüfen eines
<code>403</code> zuerst nachsehen, ob die zweite existiert.}} Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''206''' || Teilantwort eines Datei-Downloads auf eine <code>Range</code>-Anfrage; die Antwort enthält <code>Content-Range</code>
|-
| '''416''' || Der angefragte <code>Range</code> liegt hinter dem Dateiende; die Antwort nennt in <code>Content-Range</code> die wirkliche Grösse
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>); oder ein <code>Content-Encoding</code>, das der Server nicht entpacken kann - unterstützt wird allein <code>gzip</code> (siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>); oder der Anfragekörper überschreitet 10 MB bzw. - gepackt gesendet - das 400fache der gesendeten Grösse
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Vier Ursachen, unterscheidbar am <code>code</code>: <code>IDEMPOTENCY_IN_PROGRESS</code> (eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet), <code>SERVICE_UNAVAILABLE</code> bei erreichter Andrangsgrenze des Server-Profils (<code>rsv_max_parallel</code>), bei einer Anmeldung, deren Sitzungszeile nicht geschrieben werden konnte, sowie bei einem fehlgeschlagenen <code>JwtRevoke</code>. Alle vier tragen <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Ein schreibender Aufruf (POST/PUT/PATCH/DELETE) '''ohne''' <code>Idempotency-Key</code> (<code>IDEMPOTENCY_KEY_MISSING</code>); ein resumable Upload ohne Dateinamen; oder eine Anfrage, die unverschlüsselt an einen TLS-Port geschickt wurde (<code>http</code> statt <code>https</code>) - letztere wird vor Authentifizierung und Endpunkt-Skript abgewiesen
|-
| '''308''' || Zwischenantwort beim resumable Upload: das Teilstück wurde angehängt, der Upload ist noch nicht vollständig. Die Antwort trägt <code>Upload-Id</code>, <code>Upload-Offset</code> und <code>Range</code>; das Skript läuft dabei '''nicht'''
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code>
sorgt der Server selbst dafür, dass eine wiederholte Sendung '''keine
Zweitwirkung''' hat. Das gilt für '''jeden''' Endpunkt - es muss weder am Endpunkt
etwas eingestellt noch im Skript etwas programmiert werden.

{{Achtung|'''Der Header <code>Idempotency-Key</code> ist bei diesen vier Verben
Pflicht.''' Fehlt er, antwortet der Server mit '''400'''
<code>IDEMPOTENCY_KEY_MISSING</code> und das Endpunkt-Skript läuft '''nicht''' an.

Bis v1.21 lief eine Anfrage ohne den Header ungeschützt durch; der Schutz gegen
die Doppelbuchung lag damit beim Client. Ausgenommen ist allein der
JWT-Endpunkt (Anmelden, Erneuern, Abmelden) - er greift vor der Adressauflösung
und kennt die Mechanik nicht.}}

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Kein <code>Idempotency-Key</code> gesendet || '''400''' <code>IDEMPOTENCY_KEY_MISSING</code>. Das Skript läuft nicht
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* '''Ausnahme Dateiantwort:''' Liefert das Skript mit <code>SendFile</code>/<code>SendTempFile</code> eine '''Datei''' aus, wird '''nichts''' festgeschrieben - eine Dateiantwort liesse sich nicht wiedergeben, gespeichert würde eine leere 200er-Antwort. Der Schlüssel wird stattdessen wieder freigegeben, ein erneuter Abruf derselben Datei ist unschädlich.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code>. Abgeschlossene Einträge
werden nach '''30 Tagen''' gelöscht. Einträge '''ohne Ergebnis''' - sie entstehen
nur bei einem harten Abbruch des Dienstes - werden ab '''24 Stunden''' im Protokoll
gemeldet und '''anschliessend ebenfalls gelöscht'''. Das Stehenlassen wäre keine
Vorsicht, sondern eine Sperre: derselbe Vorgang mit demselben Schlüssel wäre sonst
nie wieder durchführbar.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Kostenpflichtige Module/RESTServer/Beispiel4

2026-11-05T12:39:58Z

MINERVA-Rademacker: Vorlage:-Praefix; zwei Links ohne fuehrenden Schraegstrich korrigiert [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
= Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) =

Dieses Beispiel zeigt das '''Pfad-Template-Routing''' mit Platzhaltern. Eine
Auftrags-Ressource wird über drei Endpunkte abgebildet:

{| class="wikitable"
! Methode + Pfad !! Zweck
|-
| <code>GET /orders</code> || Liste aller offenen Aufträge
|-
| <code>GET /orders/{uid}</code> || Einzelner Auftrag per UID
|-
| <code>PUT /orders/{uid}/modules/{code}</code> || Status eines Auftrags-Moduls ändern
|}

Die Platzhalter <code>{uid}</code> und <code>{code}</code> stehen im Skript als
<code>oReader.Path('uid')</code> bzw. <code>oReader.Path('code')</code> zur
Verfügung.

== Einrichtung in OBS ==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' auf <code>0.0.0.0:443</code>.
* '''Zugang:''' ''Orders-Client'' mit API-Key, Zugriff auf die drei Endpunkte.
* '''Endpunkte''' (je ein Eintrag in <code>RESTSRV_ENDPOINTS</code>, alle Profil ''Public-API''):

{| class="wikitable"
! Endpunkt !! Pfad-Template !! Skript-Methode
|-
| <code>orders</code> || <code>/orders</code> || <code>Get</code> (Liste)
|-
| <code>orders</code> || <code>/orders/{uid}</code> || <code>Get</code> (Einzel)
|-
| <code>orders</code> || <code>/orders/{uid}/modules/{code}</code> || <code>Put</code>
|}

== Endpunkt-Skript 1: <code>GET /orders</code> (Liste) ==

<syntaxhighlight lang="pascal">
// Hilfsfunktion: die FELDER eines Auftrags. Der Helfer bekommt den Writer und
// schreibt in das Objekt, das der Aufrufer schon geoeffnet hat - so laesst sich
// derselbe Auftrag einmal als Listeneintrag und einmal als ganze Antwort
// ausgeben, ohne den Code zu verdoppeln.
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TqSQL;
const cOffset: string);
begin
oWriter.Str ('uid' , qOrder.A2UID());
oWriter.Str ('nr' , qOrder.A2C('au_nr'));
oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
oWriter.Str ('status', qOrder.A2C('au_status'));
// ISO-8601 mit Offset - siehe den Hinweis unter der Liste.
oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TqSQL;
cOffset: string;
begin
cOffset := oReader.Offset();
// Die Antwort ist eine nackte Liste - RootArr vor dem ersten Eintrag.
// Findet die Abfrage nichts, ist es eine leere Liste und kein leeres
// Objekt: deshalb steht der Aufruf VOR der Abfrage.
oWriter.RootArr();

cSql := 'SELECT * FROM auftraege' +
' WHERE au_status <> ' + DB_SQLVal('9') +
' ORDER BY au_nr';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_OrderFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
</syntaxhighlight>

== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> (Einzel) ==

<syntaxhighlight lang="pascal">
// Derselbe Helfer wie im Listen-Skript - hier schreibt er in die WURZEL, weil
// der Auftrag selbst die Antwort ist. Eine eigene Fehlerfunktion braucht es
// nicht mehr: oWriter.Error setzt Statuscode, code, message, uid und traceId.
// Derselbe Helfer wie im Listen-Skript - hier schreibt er in die WURZEL,
// weil der Auftrag selbst die Antwort ist.
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TqSQL;
const cOffset: string);
begin
oWriter.Str ('uid' , qOrder.A2UID());
oWriter.Str ('nr' , qOrder.A2C('au_nr'));
oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
oWriter.Str ('status', qOrder.A2C('au_status'));
oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cSql : string;
qData : TqSQL;
lGefunden: Boolean;
cOffset : string;
begin
// Pfad-Parameter aus /orders/{uid}
cUid := oReader.Path('uid');
cOffset := oReader.Offset();
if (cUid = '') then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" fehlt');
exit;
end;

lGefunden := false;
cSql := 'SELECT * FROM auftraege WHERE sys_uid = ' + DB_SQLVal(cUid);
if (DB_SOpen(oDB, cSql, qData)) then begin
if (not qData.EoF) then begin
_OrderFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);

if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
end;
end;
</syntaxhighlight>

== Endpunkt-Skript 3: <code>PUT /orders/{uid}/modules/{code}</code> ==

<syntaxhighlight lang="pascal">
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cCode : string;
cStatus: string;
cSql : string;
qChk : TqSQL;
xMod : TqSQL;
cModUid: string;
lOk : Boolean;
begin
// Beide Pfad-Parameter
cUid := oReader.Path('uid');
cCode := oReader.Path('code');
if (cUid = '') or (cCode = '') then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" oder "code" fehlt');
exit;
end;

// Nutzdaten kommen aus dem JSON-Body. Der Rueckgabewert sagt, ob das Feld
// ueberhaupt gesendet wurde - eine eigene Hilfsfunktion dafuer braucht es
// nicht mehr.
cStatus := '';
oReader.Str('status', cStatus);
if (cStatus = '') then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
exit;
end;

// Existenzpruefung - und zugleich der Schreib-Index. Ein SELECT auf die
// sys_uid liefert beides; ein 'SELECT *' waere hier verschenkte Arbeit.
cSql := 'SELECT sys_uid FROM auftrag_module' +
' WHERE am_auftrag = ' + DB_SQLVal(cUid) +
' AND am_code = ' + DB_SQLVal(cCode) + ' LIMIT 1';
cModUid := '';
if (DB_SOpen(oDB, cSql, qChk)) then begin
if (not qChk.EoF) then begin
cModUid := qChk.A2UID();
end;
end;
DB_Close(qChk);

if (cModUid = '') then begin
oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden');
exit;
end;

// Update
// Der Satz wird ueber seine sys_uid geschrieben - qSqlRead waere hier
// ein zusaetzlicher Lesezugriff, und ein unveraenderter Wert wuerde gar
// kein Write erzeugen (SaveData liefert dann False).
xMod := qSqlInit(oDB, 'auftrag_module');
xMod.qSet('sys_uid' , cModUid);
xMod.qSet('am_status', cStatus);
// Rueckgabewert auswerten - ein Schreibfehler wirft keine Exception
lOk := xMod.SaveData(UPDATE_RECORD);
qSqlFree(xMod);

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Status konnte nicht gespeichert werden');
exit;
end;

oWriter.Str('status', 'ok');
end;
</syntaxhighlight>

== Test mit curl ==

<syntaxhighlight lang="bash">
# Liste
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders

# Einzelner Auftrag (uid als Pfad-Parameter)
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders/4711

# Modul-Status aendern (uid + code als Pfad-Parameter, status im Body)
curl -X PUT \
-H "apikey: GEHEIM123" \
-H "Content-Type: application/json" \
-d '{"status":"21"}' \
https://api.meinserver.de/orders/4711/modules/A1
</syntaxhighlight>

== Was dieses Beispiel zeigt ==

* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkt-Einträge mit eigenem Skript und eigener Berechtigung.
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript mit <code>oReader.Path('name')</code> gelesen.
* Reihenfolge der Skript-Parameter: '''<code>oReader</code> zuerst, <code>oWriter</code> danach'''.
* '''Ein Helfer bekommt den Writer''' und schreibt an der Stelle hinein, an der er gerufen wird. Derselbe <code>_OrderFelder</code> bedient den Listeneintrag und die Einzelantwort - einmal in einem <code>ObjBegin('')</code>, einmal in der Wurzel.
* Präzedenz: ein statisches Segment (z. B. <code>/orders/summary</code>) hätte Vorrang vor <code>/orders/{uid}</code>.

== Siehe auch ==

* [[OBS/Kostenpflichtige_Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]]

OBS/Kostenpflichtige Module/RESTServer/Beispiel5

2026-11-05T12:39:57Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}

=Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz=

Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem Refresh-Token.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
* '''Endpunkte''' (beide dem Profil ''Public-API'' zugeordnet):
** ''orders/{uid}'' - Auftrag lesen/Ändern
** ''orders/{uid}/material'' - Material erfassen
* '''Berechtigung:''' Zugang ''Mobile-App'' für beide Endpunkte freigeschaltet

{{Hinweis|Für das Abmelden gibt es '''keinen eigenen Endpunkt'''. Es läuft über
ein ''DELETE'' auf den JWT-Endpunkt ''auth'' und braucht daher weder eine Zeile
in ''RESTSRV_ENDPOINTS'' noch eine Berechtigung.}}

==JWT-Authentifizierungs-Skript (Zugang)==

Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'', ''TechnikerAktiv'', ''AuftragLesen'', ''AuftragVersion'', ''AuftragSpeichern'', ''MaterialAnlegen'', ''ArtikelPreis'', ''PushRegistrierungLoeschen'') sind illustrativ und projektabhängig - sie stehen für Ihre Fachlogik, nicht für eine Server-API.

{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird.}}

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das Refresh-Token aus
// _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;

//------------------------------------------------------------------------------

procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Das vorgelegte Refresh-Token hat der Server bereits geprueft und
// entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
// werden darf - und mit welchen Rechten.
if (not TechnikerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID());
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==

''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.

<syntaxhighlight lang="pascal" line>
// AuftragLesen bekommt den WRITER und schreibt die Felder des Auftrags in die
// Wurzel; nVer kommt als var-Parameter zurueck. Vorher wurde ihm das
// Antwortobjekt hineingegeben - derselbe Gedanke, nur ohne Objekt.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
nVer: Integer;
begin
cUid := oReader.Path('uid');
if (not AuftragLesen(oWriter, oReader.Claim('tenant'), cUid, nVer)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
exit;
end;
oWriter.Header('ETag', xStr(nVer));
end;

//------------------------------------------------------------------------------

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
nAktuell: Integer;
nIfMatch: Integer;
begin
// nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
// Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
// "leadless" oder "teamlead" treffen.
if (Pos(',lead,', ',' + oReader.Claim('roles') + ',') = 0) then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Diese Rolle darf nicht aendern');
exit;
end;

cUid := oReader.Path('uid');
nAktuell := AuftragVersion(cUid);
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
// Header und Error stoeren sich nicht: Error ersetzt nur den Koerper.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Auftrag wurde zwischenzeitlich geaendert');
exit;
end;

// AuftragSpeichern gibt den Rueckgabewert von SaveData durch. Ohne
// diese Pruefung antwortet der Endpunkt mit 200 und einem neuen ETag,
// obwohl nichts geschrieben wurde - siehe Scripting, Schreibfehler
// erkennen.
if (not AuftragSpeichern(cUid, oReader)) then begin // setzt Version auf nAktuell + 1
oWriter.Error(500, 'INTERNAL_ERROR', 'Der Auftrag konnte nicht gespeichert werden');
exit;
end;

oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==

''POST'' erfasst '''mehrere''' Materialpositionen in einem Aufruf: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201 mit den vergebenen Positionen.

Gegen doppelte Sendungen schickt der Client den Header ''Idempotency-Key''. '''Das
Skript muss dafür nichts tun''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:

<syntaxhighlight lang="pascal" line>
// Koerper: {"positionen":[{"artikel":"4711","menge":2},
// {"artikel":"0815","menge":1}]}
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cPos : string;
cArtikel : string;
cNeueUid : string;
nMenge : Integer;
nPreis : Double;
nGesamt : Double;
nAnz : Integer;
nI : Integer;
begin
cUid := oReader.Path('uid');

// 1) Gestalt pruefen. Count liefert 0, wenn das Feld fehlt ODER keine
// Liste ist - IsArr unterscheidet die beiden Faelle. Ein Objekt, wo
// eine Liste erwartet wird, ist etwas anderes als eine leere Liste.
nAnz := oReader.Count('positionen');
if (not oReader.IsArr('positionen')) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen muss eine Liste sein');
exit;
end;
if (nAnz = 0) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen ist leer');
exit;
end;

// 2) ALLE Positionen pruefen, BEVOR die erste gebucht wird. Sonst
// haette ein Fehler in Position 3 zwei gebuchte Zeilen und eine
// Fehlerantwort hinterlassen - der Client wiederholt und bucht die
// ersten zwei erneut.
//
// Verschachtelung steht im Pfad: Punkt fuer Felder, eckige Klammern
// fuer Listeneintraege.
for nI := 0 to nAnz - 1 do begin
cPos := 'positionen[' + IntToStr(nI) + ']';
cArtikel := '';
nMenge := 0;
oReader.Str(cPos + '.artikel', cArtikel);
oReader.Int(cPos + '.menge' , nMenge);
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oWriter.Error(422, 'VALIDATION_FAILED',
'Position ' + IntToStr(nI + 1) + ': artikel und menge sind Pflicht');
exit;
end;
end;

// 3) Buchen und antworten in EINEM Durchgang. Die Positionsnummern
// entstehen beim Buchen, also schreibt die Schleife sie an der Stelle,
// an die sie gehoeren - gesammelt und am Ende eingesetzt werden muss
// nichts.
nGesamt := 0;
oWriter.ArrBegin('positionen');
for nI := 0 to nAnz - 1 do begin
cPos := 'positionen[' + IntToStr(nI) + ']';
cArtikel := '';
nMenge := 0;
oReader.Str(cPos + '.artikel', cArtikel);
oReader.Int(cPos + '.menge' , nMenge);

cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);
if (Empty(cNeueUid)) then begin
// Der Stapel wird GESCHLOSSEN, bevor der Fehler gesetzt wird:
// oWriter.Error verwirft zwar den begonnenen Koerper, aber ein
// offener ArrBegin bleibt ein Strukturfehler - dann antwortet der
// Server 500 mit "Verschachtelung nicht geschlossen" statt mit
// dieser Meldung.
oWriter.ArrEnd;
oWriter.Error(500, 'INTERNAL_ERROR',
'Position ' + IntToStr(nI + 1) + ' konnte nicht gebucht werden');
exit;
end;

nPreis := ArtikelPreis(cArtikel) * nMenge;
nGesamt := nGesamt + nPreis;

oWriter.ObjBegin(''); // leerer Name = Listeneintrag
oWriter.Str('uid' , cNeueUid);
oWriter.Str('artikel', cArtikel);
oWriter.Int('menge' , nMenge);
// Zwei Nachkommastellen, immer mit Dezimalpunkt. Selbst
// formatiert stand bei Werten ab 1000 der Tausendertrenner im
// JSON - gueltiges JSON, falscher Wert, keine Meldung.
oWriter.Num('preis' , nPreis, 2);
oWriter.ObjEnd;
end;
oWriter.ArrEnd;

oWriter.Num('gesamt', nGesamt, 2);
oWriter.Status(201);
end;
</syntaxhighlight>

==Abmelden - ohne Endpunkt und ohne Skript==

Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren, nicht erst mit dem
Ablauf des Tokens. Dafür ist '''nichts einzurichten''': ein ''DELETE'' auf den
JWT-Endpunkt mit dem Access-Token genügt, der Server sperrt die Sitzung in
''RESTSRV_TOKEN'' und antwortet 204.

Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
Erneuerungen. Ein zweiter Aufruf ist unschädlich und bleibt 204. Kann der Server
die Sitzung nicht sperren, antwortet er '''503''' mit ''Retry-After'' - die App
wiederholt den Abmeldevorgang dann.

Nur wenn beim Abmelden zusätzlich etwas passieren soll - hier: die
Geräteregistrierung für Push löschen -, braucht es einen eigenen Endpunkt. Er
erledigt seine Fachlogik und ruft ''oWriter.JwtRevoke'':

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cAlle : string;
lAlle : Boolean;
begin
PushRegistrierungLoeschen(oReader.Claim('technikerUid'));

// Optional: {"alleGeraete": true} meldet den Techniker ueberall ab.
// Diese Entscheidung gehoert bewusst in ein Skript - sie braucht eine
// Berechtigungspruefung, die der JWT-Endpunkt nicht leisten kann.
lAlle := false;
oReader.Bool('alleGeraete', lAlle);
cAlle := IIF(lAlle, 'all', 'session');

oWriter.JwtRevoke(cAlle);
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/auth/

{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
"expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}

Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Authenticate-Skript als ''error.message''.

Auftrag lesen (liefert den ETag-Header):

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711
... ETag: 7

ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 409:

curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "If-Match: 7" -H "Content-Type: application/json" ^
-d "{\"status\":\"erledigt\"}" ^
https://api.meinserver.de/orders/4711

Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
-d "{\"positionen\":[{\"artikel\":\"A100\",\"menge\":3},{\"artikel\":\"B200\",\"menge\":1}]}" ^
https://api.meinserver.de/orders/4711/material

Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
und nichts erneut gebucht wurde.

Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):

curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
https://api.meinserver.de/auth/

Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.

Abmelden - DELETE auf denselben JWT-Endpunkt, Access-Token im Header:

curl -i -X DELETE -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/auth/

HTTP/1.1 204 No Content

Derselbe Token danach noch einmal verwendet:

curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
https://api.meinserver.de/orders/4711

HTTP/1.1 401 Unauthorized

<pre>
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20260819T091233123-00001A"
}
}
</pre>

==Was zeigt das Beispiel?==

* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422, 500.
* Eine '''Liste aus dem Körper lesen''' über ''oReader.Count'' und Pfade wie ''positionen[0].artikel'' - ohne Cast, ohne ''.Items[i]''.
* Eine '''benannte Liste von Objekten schreiben''' (''ArrBegin'' / ''ObjBegin('')'' / ''ArrEnd'') und '''Kommazahlen''' über ''oWriter.Num(name, wert, 2)''.
* '''Erst prüfen, dann schreiben''': Alle Positionen werden validiert, bevor die erste gebucht wird - sonst hinterlässt ein Fehler in Position 3 zwei gebuchte Zeilen und eine Fehlerantwort.
* '''Den Stapel schließen, bevor ein Fehler gesetzt wird''' - ein offener ''ArrBegin'' ist auch bei ''oWriter.Error'' ein Strukturfehler.
* Jeder Schreibzugriff wird auf Erfolg geprüft - ein gescheitertes ''SaveData'' darf nicht als 200 oder 201 beim Client ankommen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting#Schreibfehler erkennen|Schreibfehler erkennen]]).
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Rollenprüfung aus dem Token-Claim über ''oReader.Claim('roles')'', nicht aus dem Body.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* Anmelden, Erneuern und Abmelden über '''einen''' Endpunkt - Abmelden als ''DELETE'', ohne eigene Endpunkt-Zeile und ohne Skript.
* ''oWriter.JwtRevoke'' für den Fall, dass beim Abmelden zusätzlich Fachlogik laufen soll oder alle Geräte gemeint sind.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').

OBS/Kostenpflichtige Module/RESTServer/Beispiel6

2026-11-05T12:39:57Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}

=Beispiel 6: Datei-Upload und Ablage=

Dieses Beispiel zeigt einen Endpunkt, der '''Dateien entgegennimmt''': Ein
Aussendienst-Mitarbeiter fotografiert vor Ort ein Gerät, die App lädt das Foto zum
Auftrag hoch, der Server legt es ab und verknüpft es mit dem Vorgang.

Der Ablauf ist derselbe für Belege aus einem Scanner, Unterschriften-Bilder oder
Prüfprotokolle als PDF. Behandelt werden beide Übertragungsarten - der einfache
Upload für kleine Dateien und der fortsetzbare Upload für grosse.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App'', API-Key zufällig generiert, JWT aktiv
* '''Endpunkt:''' ''/orders/{uid}/photos'', Profil ''Public-API''
** '''Datei-Upload''' auf '''Ja''' setzen (<code>re_upload = 1</code>)
** '''Max. Upload-Grösse''' auf ''20'' (MB) setzen
* '''Berechtigung:''' Zugang ''Mobile-App'' für den Endpunkt freischalten

{{Hinweis|Ohne den Haken '''Datei-Upload''' lehnt der Server jeden Upload mit
'''415''' ab und das Skript läuft gar nicht erst an. Das ist die häufigste Ursache,
wenn ein Upload "ohne erkennbaren Grund" scheitert.}}

==Was der Server erledigt, bevor das Skript läuft==

Der Server nimmt die Datei entgegen, prüft die Grösse, legt sie in einem temporären
Verzeichnis ab und übergibt dem Skript drei Parameter:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei
|-
| <code>oReader.UploadName()</code> || Originaldateiname, wie ihn der Client gesendet hat
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei
|-
| <code>oReader.UploadSha()</code> || SHA-256 der gespeicherten Datei (hex, klein)
|}

Zwei Dinge sind beim Schreiben des Skripts wichtig:

* '''Bei Uploads gibt es keinen JSON-Körper''' - <code>oReader.HasBody()</code> ist <code>false</code>, der Request-Body ist die Datei. Zusatzangaben (Kategorie, Bemerkung) kommen deshalb als '''Query-Parameter''' mit - oder, bei <code>multipart/form-data</code>, als weitere '''Formularfelder''', lesbar über <code>oReader.Form('<name>')</code>.
* '''Die temporäre Datei bleibt liegen, wenn das Skript sie nicht übernimmt.''' Der Server räumt sie nicht selbst weg.

==Endpunkt-Skript ''/orders/{uid}/photos''==

Das Skript prüft den Dateityp, baut einen Zielpfad aus Auftrag und Zeitstempel,
verschiebt die Datei dorthin und schreibt einen Verweis in die Datenbank.

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
const ZIEL_BASIS = 'D:\OBS\Daten\Auftragsfotos\';
var cUid : string;
cTmpPfad : string;
cOrigName : string;
cTyp : string;
cEndung : string;
cKategorie: string;
cZielDir : string;
cZielName : string;
cZielPfad : string;
qNeu : TqSQL;
begin
cUid := oReader.Path('uid');
cTmpPfad := oReader.UploadPath();
cOrigName := oReader.UploadName();
cTyp := oReader.UploadType();
cKategorie := oReader.Param('kategorie'); // Query-Parameter, nicht Body

// 1) Gehoert der Auftrag zum Mandanten aus dem Token?
if (not AuftragGehoertZuMandant(oReader.Claim('tenant'), cUid)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
exit;
end;

// 2) Dateityp gegen eine Whitelist pruefen - niemals gegen eine
// Blacklist, und niemals dem Content-Type allein vertrauen.
cEndung := Lower(ExtractFileExt(cOrigName));
if ((cEndung <> '.jpg') and (cEndung <> '.jpeg') and (cEndung <> '.png') and (cEndung <> '.pdf')) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Nur JPG, PNG und PDF sind zulässig');
exit;
end;

// 3) Zielname selbst bilden. Den Originalnamen NICHT als Pfad
// verwenden - er kommt vom Client und kann '..\' enthalten.
cZielDir := ZIEL_BASIS + DToS(Date()) + '\' + cUid + '\';
cZielName := DToSF(Now()) + '_' + GlobalUID() + cEndung;
cZielPfad := cZielDir + cZielName;

MyForceDirectories(cZielDir);

if (not FMove(cTmpPfad, cZielPfad)) then begin
// Fehlgeschlagenes Verschieben ist ein Serverproblem -> 500.
// Der Idempotency-Key wird bei 5xx wieder freigegeben, der
// Client darf denselben Schluessel erneut senden.
oWriter.Error(500, 'INTERNAL_ERROR', 'Datei konnte nicht abgelegt werden');
exit;
end;

// 4) Verweis in der Datenbank ablegen
qNeu := qSqlInit(oDB, 'AUFTRAG_DOKUMENT');
qNeu.qSet('ad_auftrag' , cUid);
qNeu.qSet('ad_pfad' , cZielPfad);
qNeu.qSet('ad_dateiname', cOrigName);
qNeu.qSet('ad_typ' , cTyp);
qNeu.qSet('ad_kategorie', cKategorie);
qNeu.qSet('ad_datum' , Now());
// Rueckgabewert auswerten: ohne das bestaetigt der Endpunkt eine
// Ablage, die es nicht gibt - die Datei liegt dann im Zielverzeichnis,
// aber ohne Verweis in der Datenbank.
if (not qNeu.SaveData(NEW_RECORD)) then begin
qSqlFree(qNeu);
oWriter.Error(500, 'INTERNAL_ERROR', 'Verweis konnte nicht gespeichert werden');
exit;
end;
qSqlFree(qNeu);

// 5) 201 mit Location auf die abgelegte Datei
oWriter.Str('dateiname', cZielName);
oWriter.Int('groesse' , FSize(cZielPfad));
oWriter.Status(201);
oWriter.Header('Location', '/orders/' + cUid + '/photos/' + cZielName);
end;
</syntaxhighlight>

{{Hinweis|Soll die Datei statt in ein Verzeichnis in das '''OBS-Dokumenten-System'''
wandern, ersetzt der DMS-Aufruf die Schritte 3 bis 5. Welche Funktion dafür
zuständig ist, hängt vom eingesetzten Dokumenttyp ab - bitte mit dem OBS-Support
klären.}}

{{Hinweis|'''Fünf Fehlerausgänge, fünf Zeilen.''' Vorher baute jeder von ihnen
sein ''error''-Objekt, seinen Statuscode und seine ''traceId'' von Hand - fünfmal
dasselbe Muster, das an einer Stelle abweichen kann, ohne dass es auffällt.
<code>oWriter.Error</code> setzt alles davon, auch die ''traceId'', und verwirft
einen bereits begonnenen Körper. Ein ''exit'' danach genügt.}}

==Test mit curl==

Einfacher Upload einer Datei (''-F'' erzeugt ''multipart/form-data''):

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-F "datei=@C:\Fotos\geraet.jpg" ^
"https://api.meinserver.de/orders/4711/photos?kategorie=VORHER"

Antwort:

HTTP/1.1 201 Created
Location: /orders/4711/photos/20260817091233_A1B2C3.jpg
X-Trace-Id: 20260817T091233123-00001A

{"dateiname":"20260817091233_A1B2C3.jpg","groesse":248113}

Ein Upload an einen Endpunkt '''ohne''' Upload-Freigabe:

HTTP/1.1 415 Unsupported Media Type

Eine Datei über der eingestellten Grenze:

HTTP/1.1 413 Payload Too Large

==Grosse Dateien: fortsetzbarer Upload==

Bei einem Foto aus dem Mobilfunknetz reisst die Verbindung schnell einmal ab. Für
solche Fälle überträgt der Client die Datei in Teilstücken und kann nach einem
Abbruch dort weitermachen, wo er aufgehört hat. '''Am Endpunkt-Skript ändert sich
dafür nichts''' - der Server sammelt die Teilstücke selbst ein und ruft das Skript
erst auf, wenn die Datei vollständig ist.

Der erste Teil trägt den Dateinamen (Base64-kodiert im Header
<code>Upload-Metadata</code>) und liefert eine <code>Upload-Id</code> zurück:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes 0-1048575/5000000" ^
-H "Upload-Metadata: filename Z2VyYWV0LmpwZw==,filetype aW1hZ2UvanBlZw==" ^
--data-binary "@teil1.bin" ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Id: 7f2a9c84...
Upload-Offset: 1048576
Range: bytes=0-1048575

Jeder weitere Teil sendet die ''Upload-Id'' mit. Der letzte Teil bekommt die
normale Antwort des Skripts (hier '''201'''). Nach einem Abbruch fragt der Client
den Stand ab und setzt dort auf:

curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
-H "Content-Range: bytes */5000000" -H "Upload-Id: 7f2a9c84..." ^
https://api.meinserver.de/orders/4711/photos

HTTP/1.1 308 Resume Incomplete
Upload-Offset: 3145728

{{Hinweis|Der Zwischenstand liegt im Arbeitsspeicher des Dienstes. Wird der
REST-Dienst neu gestartet, muss ein unvollständiger Upload von vorn beginnen.}}

==Doppelte Uploads vermeiden==

Bricht die Verbindung ab, nachdem der Server die Datei schon abgelegt hat, würde ein
Wiederholversuch dasselbe Foto ein zweites Mal einliefern. Dagegen sendet der Client
den Header <code>Idempotency-Key</code> - für jedes Foto einen eigenen, über alle
Wiederholversuche hinweg denselben:

-H "Idempotency-Key: foto-4711-0003"

Der Server erkennt die Wiederholung und liefert die '''gespeicherte 201-Antwort'''
samt Header <code>Idempotent-Replay: true</code> zurück, ohne das Skript erneut zu
starten. Es entsteht also weder eine zweite Datei noch ein zweiter DB-Eintrag.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.

==Was zeigt das Beispiel?==

* Endpunkt mit '''Datei-Upload-Freigabe''' (<code>re_upload</code>) und eigener Grössenbegrenzung.
* Zugriff auf die hochgeladene Datei über ''oReader.UploadPath()'', ''UploadName()'' und ''UploadType()''.
* Zusatzangaben als '''Query-Parameter''' oder Formularfeld, weil bei Uploads kein JSON-Körper vorliegt.
* '''Whitelist''' für zulässige Dateitypen und ein '''selbst gebildeter Zielname''' - der Originalname landet nie im Pfad.
* Übernahme der temporären Datei mit ''FMove''; ohne diesen Schritt bleibt sie liegen.
* Antwort mit '''201''' und ''Location''-Header.
* Fortsetzbarer Upload ohne jede Änderung am Skript.
* Schutz gegen doppelte Einlieferung über den ''Idempotency-Key''.

==Siehe auch==

* [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] - Upload-Parameter und Protokoll im Detail
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] - Freigabe, Grössenlimit, Idempotenz
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5]] - Schreibzugriff mit Statuscodes und ETag

OBS/Kostenpflichtige Module/RESTServer/Beispiel3

2026-11-05T12:39:56Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}

=Beispiel 3: Datensatz anlegen mit JSON-Body=

Dieses Beispiel zeigt einen Endpunkt mit allen vier CRUD-Zugriffen (GET, POST, PUT und - anstelle von DELETE - PATCH, siehe den Hinweis beim Schliessen). Es geht um Tickets eines externen Servicedesks, der Tickets über den OBS REST-Server in OBS einliefern, abrufen, aktualisieren und schliessen kann.

{{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über einen Query-Parameter (''?id...''). Alternativ lässt sich dieselbe Ressource über ein Pfad-Template wie ''/tickets/{id}'' ansprechen; die ID steht dann als ''oReader.Path('id')'' bereit. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].}}

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'', Bindung 0.0.0.0:443
* '''Zugang:''' ''Servicedesk-X''
** API-Key: zufällig generiert
** Host: ''servicedesk.firma.de'' (DNS-gebunden, IP-Zugriff wird abgelehnt)
** JWT: nicht aktiv
* '''Endpunkt:''' ''tickets/v1'', Profil ''Public-API''
* '''Berechtigung:''' Zugang ''Servicedesk-X'' für Endpunkt ''tickets/v1'' freigeschaltet

==Endpunkt-Skript ''tickets/v1''==

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Hilfsprozedur: die FELDER eines Tickets. Sie bekommt den Writer und schreibt
// in das Objekt, das der Aufrufer geoeffnet hat - einmal als Listeneintrag,
// einmal in die Wurzel. Ein Helfer, der ein Fragment als String zurueckgibt,
// waere der alte Weg; dabei ging die Reihenfolge im Zusammenbau verloren.
//------------------------------------------------------------------------------

procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
const cOffset: string);
begin
oWriter.Str ('id' , qTicket.A2UID());
oWriter.Str ('nr' , qTicket.A2C('ti_nr'));
oWriter.Str ('betreff', qTicket.A2C('ti_betreff'));
oWriter.Str ('status' , qTicket.A2C('ti_status'));
oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
// Zeitpunkte gehen als ISO-8601 MIT OFFSET ueber die Leitung, nicht im
// SQL-Format: DTToSQL liefert 'JJJJ-MM-TT hh:mm:ss' ohne Zeitzone, und der
// Konsument muss dann raten, in welcher er steht. RestIsoFromDate nimmt den
// Offset des Servers dazu. Ein leeres Datum ergibt null, nicht 1899.
oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;

// Fuer den Body-Zugriff und fuer Fehlerantworten braucht es keine eigenen
// Hilfsfunktionen mehr: oReader liest typisiert, oWriter.Error baut die
// vollstaendige Fehlerhuelle samt traceId.

//------------------------------------------------------------------------------
// GET /tickets/v1?id=... - einzelnes Ticket
// GET /tickets/v1 - alle offenen Tickets
//------------------------------------------------------------------------------

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TxFQuery;
cId : string;
cOffset : string;
lGefunden: Boolean;
begin
cId := oReader.Param('id');
// Der Offset des Servers geht in jeden Zeitstempel der Antwort.
cOffset := oReader.Offset();

if (not Empty(cId)) then begin
lGefunden := false;
cSql := 'SELECT * FROM tickets WHERE sys_uid = ' + DB_SQLVal(cId);
if (DB_SOpen(oDB, cSql, qData)) then begin
// EoF gehoert dazu: DB_SOpen sagt nur, dass die ABFRAGE lief.
if (not qData.EoF) then begin
_TicketFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);

if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
end;
end else begin
// Die Liste ist eine nackte Liste. RootArr steht vor der Abfrage:
// kein Treffer heisst leere Liste, nicht leeres Objekt.
oWriter.RootArr();
cSql := 'SELECT * FROM tickets WHERE ti_status <> "9" ORDER BY ti_aend_dat DESC';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_TicketFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
end;

//------------------------------------------------------------------------------
// POST /tickets/v1 - neues Ticket anlegen
// Body: { "betreff":"...", "beschr":"..." }
//------------------------------------------------------------------------------

procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket : TqSQL;
cId : string;
cBetreff: string;
cBeschr : string;
lOk : Boolean;
begin
// HasBody unterscheidet "kein Koerper" von "Koerper ohne das Feld" - das
// erste ist ein 400, das zweite ein 422.
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cBetreff := '';
cBeschr := '';
oReader.Str('betreff', cBetreff);
oReader.Str('beschr' , cBeschr);

if (Empty(cBetreff)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
exit;
end;

cId := GetNewId(oDB);

xTicket := qSqlInit(oDB, 'tickets');
xTicket.lNoSysUID := True;
try
xTicket.qSet('sys_uid' , cId);
xTicket.qSet('ti_nr' , DB_NeuNum(oDB, 'tickets', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
xTicket.qSet('ti_betreff' , cBetreff);
xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_status' , '1');
xTicket.qSet('ti_anl_dat' , Now());
xTicket.qSet('ti_aend_dat', Now());
// SaveData liefert einen Boolean. Ein SQL-Fehler - etwa Duplicate entry
// auf einem eindeutigen Index - wirft KEINE Exception und steht in
// keinem Protokoll. Ohne diese Auswertung antwortet der Endpunkt mit
// 201, ohne etwas angelegt zu haben.
lOk := xTicket.SaveData(NEW_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
exit;
end;

oWriter.Str('id' , cId);
oWriter.Str('status', 'created');
oWriter.Status(201);
oWriter.Header('Location', '/tickets/v1?id=' + cId);
end;

//------------------------------------------------------------------------------
// PUT /tickets/v1 - Ticket aktualisieren
// Body: { "id":"...", "status":"...", "beschr":"..." }
//------------------------------------------------------------------------------

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
lOk : Boolean;
cId : string;
cStat : string;
cBeschr: string;
begin
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cId := '';
cStat := '';
cBeschr := '';
oReader.Str('id' , cId);
oReader.Str('status', cStat);
oReader.Str('beschr', cBeschr);

if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

// Zum Aendern qSqlInit mit sys_uid, nicht qSqlRead: qSqlRead liest den
// Altsatz und schreibt nur Aenderungen - ein unveraenderter Wert erzeugt
// gar kein Write und SaveData liefert False.
xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
if (not Empty(cStat)) then xTicket.qSet('ti_status' , cStat);
if (not Empty(cBeschr)) then xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geaendert werden');
exit;
end;

oWriter.Str('status', 'updated');
end;

//------------------------------------------------------------------------------
// PATCH /tickets/v1?id=... - Ticket schliessen (Soft-Delete via Status=9)
//
// NICHT als DELETE: 'Delete' ist in der Skriptsprache eine Standardprozedur,
// eine eigene Prozedur dieses Namens laesst sich nicht uebersetzen. Solange das
// so ist, laeuft ein Loeschen ueber PATCH oder POST. Siehe den Hinweis unten.
//------------------------------------------------------------------------------

procedure Patch(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
cId : string;
lOk : Boolean;
begin
cId := oReader.Param('id');
if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
xTicket.qSet('ti_status' , '9');
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
exit;
end;

oWriter.Str('status', 'closed');
end;
</syntaxhighlight>

{{Achtung|'''Ein DELETE-Endpunkt kann derzeit kein Skript haben.''' Der Server
ruft die Prozedur, die genauso heisst wie das HTTP-Verb - für DELETE also
<code>Delete</code>. Dieser Name ist in der Skriptsprache belegt
(Standardprozedur zum Löschen aus einer Zeichenkette), und die Deklaration
lässt sich nicht übersetzen; die Meldung nennt dabei nur die Zeile, nicht die
Ursache. Bis das gelöst ist: das Löschen als <code>PATCH</code> oder
<code>POST</code> mit einer Aktion abbilden. Das Abmelden am JWT-Endpunkt ist
davon nicht betroffen - es läuft als DELETE '''ohne''' Skript vollständig in
der Engine.}}

==Aufruf mit curl==

Liste aller offenen Tickets:

curl -H "apikey: [API-KEY]" https://api.meinserver.de/tickets/v1

Einzelnes Ticket:

curl -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

Neues Ticket anlegen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"betreff\":\"Drucker offline\",\"beschr\":\"Etage 2, Raum 23\"}" ^
https://api.meinserver.de/tickets/v1

Ticket aktualisieren:

curl -X PUT -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"id\":\"abc-123\",\"status\":\"2\"}" ^
https://api.meinserver.de/tickets/v1

Ticket schliessen:

curl -X PATCH -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

==Aufruf aus PHP==

<syntaxhighlight lang="php" line>
<?php
$apikey = '[API-KEY]';
$base = 'https://api.meinserver.de/tickets/v1';

function rest($method, $url, $apikey, $body = null) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL , $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
$headers = ['apikey: ' . $apikey];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}

// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
'betreff' => 'Drucker offline',
'beschr' => 'Etage 2, Raum 23'
]);
$id = $neu['id'];

// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2']);

// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
?>
</syntaxhighlight>

==Was zeigt das Beispiel?==

* Saubere Trennung der CRUD-Methoden in einem Endpunkt.
* Verwendung des JSON-Body für komplexere Eingangsdaten (POST, PUT).
* Verwendung von Query-Parametern für einfache Werte (GET, PATCH).
* Soft-Delete über Status-Änderung statt physischer Löschung - und warum er als PATCH und nicht als DELETE läuft.
* Eindeutige Audit-UIDs (''Y00CXXXXxx'') für jeden DB-Zugriff zur Nachvollziehbarkeit.
* Host-gebundener Zugang als zweite Sicherheitsebene neben dem API-Key.
* Alternativ: ID per Pfad-Parameter statt Query-Parameter (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4]]).

OBS/Kostenpflichtige Module/RESTServer/Beispiel2

2026-11-05T12:39:55Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}

=Beispiel 2: Zeiterfassung als komplette Webanwendung=

Dieses Script dient zur Zeiterfassung über den REST-Server. Bei Seitenaufruf wird eine Liste von Kunden geladen und in einer Liste angezeigt.

Durch Rechtsklick auf einen Eintrag wird eine Liste an zugehörigen Tätigkeiten geladen, die nach Klick einen Timer starten.

Per Javascript werden Startzeit, Startdatum und andere Informationen wie Kunde und Personalnummer über die PHP-Scripte und das Endpunkt-Script in einer Datenbank gespeichert.

Der Status wird hierbei auf "1" gesetzt. Pausenzeiten werden nach Beenden einer Pause in der Datenbank gespeichert.

Durch Drücken des Stop-Buttons wird eine Lightbox mit einer Zusammenfassung aller zum Timer gehörenden Daten angezeigt. Hier hat man die Möglichkeit Tätigkeiten, abgelaufene Zeit und

Pausenzeit nachträglich zu bearbeiten. Durch Klick auf "Speichern" oder Druck auf F2 werden Endzeit und Enddatum gespeichert und der Status auf "21" gesetzt.

Nach Reload der Webseite wird anhand des Status in der Datenbank nach laufenden Timern gesucht und diese gegebenenfalls gestartet.

= Endpunkt-Script =
<syntaxhighlight lang="pascal">
procedure _AddJob(oWriter: TxRestWriter; id: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT CONCAT(za_text, ":",sys_uid) AS Job FROM zeiterfart ' +
'WHERE za_psnr = ' + DB_SQLVal(id) + ' AND za_inaktiv <> "1" ' +
'ORDER BY za_order';
if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('Job'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddCustomer(oWriter: TxRestWriter);
var cSql : String;
A_Query : TxFQuery;
begin
cSql :=' SELECT * FROM' +
' (SELECT' +
' ps_nr,' +
' ps_such AS Kunde,' +
' perssta.sys_uid AS ps_sys_uid,' +
' "PE" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN perssta ON se_ref1 AND perssta.sys_uid = se_ref2' +
' WHERE se_nr = 0087' +
' AND ps_nr <> 100000' +
' UNION SELECT p_nr AS ps_nr,' +
' p_name1 AS ps_such,' +
' projekte.sys_uid AS ps_sys_uid,' +
' "PR" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN projekte ON se_ref1 = p_nr' +
' AND projekte.sys_uid = se_ref2 WHERE se_nr = 0087)' +
' A WHERE ps_nr IS NOT NULL' +
' ORDER BY Kunde ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('Kunde'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddID(oWriter: TxRestWriter; kunde: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql :=' SELECT * FROM' +
' (SELECT' +
' ps_nr,' +
' ps_such AS Kunde,' +
' perssta.sys_uid AS ps_sys_uid,' +
' "PE" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN perssta ON se_ref1 AND perssta.sys_uid = se_ref2' +
' WHERE se_nr = 0087' +
' AND ps_nr <> 100000' +
' UNION SELECT p_nr AS ps_nr,' +
' p_name1 AS ps_such,' +
' projekte.sys_uid AS ps_sys_uid,' +
' "PR" AS TYP' +
' FROM eigenschaften' +
' LEFT JOIN projekte ON se_ref1 = p_nr' +
' AND projekte.sys_uid = se_ref2 WHERE se_nr = 0087)' +
' A WHERE ps_nr IS NOT NULL' +
' AND Kunde = ' + DB_SQLVal(kunde) +
' ORDER BY Kunde ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('ps_nr'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _AddCHECK(oWriter: TxRestWriter);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT ze_starttime, zeiterfuser.sys_uid AS sysuid, zk_psnr, ' +
'za_text, ps_such, ze_startdate FROM ' +
'zeiterfuser LEFT JOIN zeiterfkomm ON ' +
'zk_messunguid = zeiterfuser.SYS_UID LEFT JOIN zeiterfart ' +
'ON zeiterfart.sys_uid = zeiterfuser.ze_uid AND ' +
'za_psnr = zeiterfkomm.zk_psnr LEFT JOIN perssta ON ' +
'ps_nr = zeiterfkomm.zk_psnr WHERE ze_status = 01 ';

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('ze_starttime'));
oWriter.Str('', A_Query.A2C('zk_psnr'));
oWriter.Str('', A_Query.A2C('za_text'));
oWriter.Str('', A_Query.A2C('ps_such'));
oWriter.Str('', A_Query.A2C('sysuid'));
oWriter.Str('', A_Query.A2C('ze_startdate'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

procedure _getPauseTime(oWriter: TxRestWriter; sysuid: String);
var cSql : String;
A_Query : TxFQuery;
begin
cSql := 'SELECT * FROM zeiterfuser WHERE sys_uid = ' + DB_SQLVal(sysuid);

if (DB_xSOpen('Y009LHNBTY', oDB, cSql, A_Query, False)) then begin
while (not A_Query.EoF) do begin
oWriter.Str('', A_Query.A2C('ze_pausezeit'));
A_Query.Next();
end;
end;
DB_Close(A_Query);
end;

//----------------Funktionen----------------------------------//

procedure POST(oReader: TxRestReader; oWriter: TxRestWriter);
var cChoice: String;
begin
cChoice := oReader.Param('choice');

// Jede dieser Antworten ist eine nackte Liste von Zeichenketten - genau
// so, wie das Javascript sie mit JSON.parse erwartet. RootArr sagt das
// und steht deshalb VOR dem ersten Eintrag.
if (cChoice = 'job') then begin
oWriter.RootArr();
_AddJob(oWriter, oReader.Param('id'));
end else if (cChoice = 'customer') then begin
oWriter.RootArr();
_AddCustomer(oWriter);
end else if (cChoice = 'id') then begin
oWriter.RootArr();
_AddID(oWriter, oReader.Param('selectedKunde'));
end else if (cChoice = 'check') then begin
oWriter.RootArr();
_AddCHECK(oWriter);
end else if (cChoice = 'pauseTime') then begin
oWriter.RootArr();
_GetPauseTime(oWriter, oReader.Param('sysuid'));
end else begin
// Eine unbekannte Auswahl war vorher eine leere Antwort - der Aufrufer
// sah einen Tippfehler nicht. Jetzt sagt es der Statuscode.
oWriter.Error(422, 'VALIDATION_FAILED', 'Unbekannte Auswahl: ' + cChoice);
end;
end;

procedure PUT(oReader: TxRestReader; oWriter: TxRestWriter);
var xZeit : TqSQL;
cUSER_SYSUID : String;
cKOMM_SYSUID : String;
lNew : Boolean;
cSql : String;
dDBNow : TDateTime;
cChoice : String;
begin
cChoice := oReader.Param('choice');
writeln('Choice: ' + cChoice);

if (cChoice = 'start') then begin
dDBNow := DB_Now(oDB);
lNew := True;
if (empty(cUSER_SYSUID)) then begin
cUSER_SYSUID := GetNewId(oDB);
end;

xZeit := qSqlInit(oDB, 'zeiterfuser');
xZeit.lNoSysUID := True;

writeln('SYSUID: ' + oReader.Param('jobID'));

xZeit.qSet('ze_user' , oReader.Param('user'));
xZeit.qSet('ze_starttime' , oReader.Param('uhrzeit'));
xZeit.qSet('ze_eigen' , '0101');
xZeit.qSet('ze_startdate' , oReader.Param('datum'));
xZeit.qSet('ze_endtime' , oReader.Param('endTime'));
xZeit.qSet('ze_enddate' , oReader.Param('endDate'));
xZeit.qSet('ze_zeit' , '0');
xZeit.qSet('ze_pausezeit' , '0');
xZeit.qSet('ze_status' , oReader.Param('status'));
xZeit.qSet('ze_berechnen' , 0);
xZeit.qSet('ze_officestar' , 0);
xZeit.qSet('ze_repa' , 0);
xZeit.qSet('ze_vorbereitung' , 0);
xZeit.qSet('ze_uid' , oReader.Param('jobID'));
xZeit.qSet('sys_uid' , cUSER_SYSUID);

// SaveData meldet einen Fehler ueber den RUECKGABEWERT, nicht ueber eine
// Exception. Ohne diese Pruefung antwortet der Endpunkt mit Erfolg,
// obwohl nichts geschrieben wurde.
if (not xZeit.SaveData(lNew)) then begin
qSQLFree(xZeit);
oWriter.Error(500, 'INTERNAL_ERROR', 'Zeiterfassung konnte nicht gespeichert werden');
exit;
end;
qSQLFree(xZeit);

//---------------------------------------------------------------------

xZeit := qSqlInit(oDB,'ZEITERFKOMM');
xZeit.lNoSysUID := True;

if (empty(cKOMM_SYSUID)) then begin
cKOMM_SYSUID := GetNewId(oDB);
end;

xZeit.qSet('zk_psnr' , oReader.Param('psnr'));
xZeit.qSet('zk_starttime' , oReader.Param('uhrzeit'));
xZeit.qSet('zk_startdate' , oReader.Param('datum'));
xZeit.qSet('zk_kommentar' , oReader.Param('comm'));
xZeit.qSet('zk_messunguid' , cUSER_SYSUID);
xZeit.qSet('sys_uid' , cKOMM_SYSUID);

if (not xZeit.SaveData(lNew)) then begin
qSQLFree(xZeit);
oWriter.Error(500, 'INTERNAL_ERROR', 'Kommentar konnte nicht gespeichert werden');
exit;
end;
qSQLFree(xZeit);

// Die UID steht jetzt in einem FELD und nicht mehr als nackter Text im
// Koerper. Der Writer kann nur JSON schreiben - und das ist gut so:
// eine Antwort, die manchmal 'ERROR: ...' und manchmal eine UID war,
// liess sich vom Aufrufer nicht unterscheiden. Das Javascript liest
// dafuer JSON.parse(...).uid, siehe timer.js.
oWriter.Str('uid', cUSER_SYSUID);

end else if (cChoice = 'stop') then begin

// Jeder Wert aus der Anfrage geht durch DB_SQLVal - auch die, die wie
// Zahlen aussehen. Der Kommentar ist Freitext aus dem Browser, und
// ohne Quoting beendet ein Apostroph darin das SQL-Statement.
cSql := 'UPDATE zeiterfuser, zeiterfkomm ' +
' SET zeiterfuser.ze_zeit = ' + DB_SQLVal(oReader.Param('elapsedTime')) +
', zeiterfuser.ze_endtime = ' + DB_SQLVal(oReader.Param('vergZeit')) +
', zeiterfuser.ze_enddate = ' + DB_SQLVal(oReader.Param('stopTimeValue')) +
', zeiterfuser.ze_pausezeit = ' + DB_SQLVal(oReader.Param('elapsedPauseTime')) +
', zeiterfuser.ze_status = ' + DB_SQLVal(oReader.Param('status')) +
', zeiterfkomm.zk_kommentar = ' + DB_SQLVal(oReader.Param('comment')) +
' WHERE zeiterfuser.sys_uid = ' + DB_SQLVal(oReader.Param('uid')) +
' AND zeiterfkomm.zk_messunguid = ' + DB_SQLVal(oReader.Param('uid'));

if (DB_SQLExec(oDB, cSql)) then begin
oWriter.Str('status', 'ok');
end else begin
// Ein Fehlschlag ist ein 500 und keine 200 mit dem Wort 'Fehler!'
// im Koerper - sonst haelt der Aufrufer ihn fuer einen Erfolg.
oWriter.Error(500, 'INTERNAL_ERROR', 'Die Daten konnten nicht gespeichert werden');
end;

end else if (cChoice = 'pause') then begin
writeln('Pausezeit: ' + oReader.Param('pauseTime'));
cSql := 'UPDATE zeiterfuser SET ze_pausezeit ' +
'= ze_pausezeit + ' + DB_SQLVal(oReader.Param('pauseTime')) +
' WHERE sys_uid = ' + DB_SQLVal(oReader.Param('sysuid'));

if (DB_SQLExec(oDB, cSql)) then begin
oWriter.Str('status', 'ok');
end else begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Die Pausenzeit konnte nicht gespeichert werden');
end;

end else begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Unbekannte Auswahl: ' + cChoice);
end;
end;
</syntaxhighlight>

= HTML-Datei index.php =
<syntaxhighlight lang="html">
<!DOCTYPE html>
<html lang="de-DE">
<head>
<title>Ihr IT-Partner in Stade - Ernst Bergau GmbH</title>
<link rel="stylesheet" type="text/css" href="timestyle.css">
</head>
<script>
<?php
include('timer.js');
?>
</script>
<body>




<textarea id="search" type="text" rows="1" cols="50" oninput="searchCustomers(this.value)"></textarea>

<div class="kundenliste">
<ul id="kundenListe"></ul>
</div>
<table class="timer">
<tbody id="timerList"></tbody>
</table>
<table class="tabelleUeberschriften">
<thead>
<tr>
<th class="kunde">Kunde</th>
<th class="konto">Konto</th>
<th class="laufzeit">Laufzeit</th>
<th class="status">Status</th>
</tr>
</thead>
</table>

<div class="lightbox" id="lightbox">
<label class="commLabel" id="commLabel" for="comment">Kommentar</label>
<textarea class="comment" id="comment" rows="4" cols="50"></textarea>

<div class="bezZeitkonto">Zeitkonto</div>
<select class="dropButtonsLightbox" id="tätigkeit2Dropdown"></select>

<div class="bezDatum">Startdatum</div>
<input type="date" class="date" id="date">

<textarea disabled class="uhrzeit" id="uhrzeit"></textarea>

<div class="bezPerson">Person</div>
<textarea disabled class="eingPerson" id="eingPerson"></textarea>
<textarea disabled class="eingPersonZusatz" id="eingPersonZusatz"></textarea>

<div class="Std">Std</div>
<input type="number" class="outStd" id="outStd">
<div class="Min">Min</div>
<input type="number" class="outMin" id="outMin">
<div class="Sek">Sek</div>
<input type="number" class="outSek" id="outSek">

<div class="Pausenzeiten">Davon Pausenzeiten</div>
<div class="Std2">Std</div>
<input type="number" class="outStd2" id="outStd2">
<div class="Min2">Min</div>
<input type="number" class="outMin2" id="outMin2">
<div class="Sek2">Sek</div>
<input type="number" class="outSek2" id="outSek2">

<button class="saveButton" id="saveButton">Speichern</button>
<button class="closeButton" id="closeButton" onclick="closeLightboxOnSchliessen()">Schließen</button>
</div>

<div id="zweiteListe">
<ul id="taetigkeitListe"></ul>
</div>
</body>
</html>

</syntaxhighlight>

= Javascript-Datei timer.js =
<syntaxhighlight lang="javascript">
var api_key = 'Y00C75PODJ';
var url = 'http://127.0.0.1:8099/Zeiterfa/zeiterfa/v1';
var zaehler = -1;
var timerInterval;
var pauseTimerInterval;
var startTimeValue;
var selectedID = 0;
var elapsedTime;
var uid;
var idStop;
var time;
var selID = [];
var job = [];
var sys_uid = [];
var timers = [];
var pauseTimers = [];
var pauseTime = [];
var startdate = [];
var uhrzeit = [];
var datum = [];
var statusTimer = [];
var selectedJob = [];
var selectedKunde = [];
var tempSelectedKunde = [];
var parameter = [];

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------------Seitenaufruf---------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Bei Seitenaufruf werden die Funktionen----//
//----getCustomer und checkTimer aufgerufen und----//
//----die Kundenliste gefüllt und geprüft,----//
//----ob laufende timer vorhanden sind----//

window.onload = function() {

getCustomer();
checkTimer();
}

//-----------------------------------------------------------------------------------------------------------------------//
//-------------------------------------------------Daten auslesen--------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Eine Liste der Kunden wird ausgelesenund gespeichert----//

function getCustomer() {

var method = 'POST';
var choice = 'customer';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
populateListeKunde(responseData);
}
};
request.send(params);
}

//----Bei Rechtsklick auf Kunden wird----//
//----seine ID ausgelesen und gespeichert----//

function getCustomerID(selectedKunde, callback) {

var method = 'POST';
var choice = 'id';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&selectedKunde=" + encodeURIComponent(selectedKunde);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
selectedID = JSON.parse(request.responseText);
callback(selectedID);
}
};
request.send(params);
}

//----Anhand der Kunden-ID wird eine Liste von Tätigkeiten----//
//----für jeden Kunden ausgelesen und gespeichert----//

function getJob(id, callback) {

var method = 'POST';
var choice = 'job';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&id=" + encodeURIComponent(id);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
var Data = responseData.toString();
var teile = Data.split(",");
var jobid = [];

for (i=0; i<teile.length; i++) {
job[i] = teile[i].split(":")[0];
jobid[i] = teile[i].split(":")[1];
}
callback(job, jobid);
}
};
request.send(params);
}

//----Tätigkeitsliste wird nochmal zur Weiterverarbeitung gelesen----//

function getJobs(id) {

var method = 'POST';
var choice = 'job';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&id=" + encodeURIComponent(id);

var request = new XMLHttpRequest();

request.open("POST", "getData.php", false);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
var responseData = JSON.parse(request.responseText);
var data = responseData.toString();
var teile = data.split(",");
var jobid = [];

for (var i = 0; i < teile.length; i++) {
job[i] = teile[i].split(":")[0];
jobid[i] = teile[i].split(":")[1];
}
}
};
request.send(params);
}

//----Gespeicherte Pausezeit wird ausgelesen----//

function getPauseTime(sysuid, id) {

var method = 'POST';
var choice = 'pauseTime';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&sysuid=" + encodeURIComponent(sysuid);

var request = new XMLHttpRequest();

request.open("POST", "getData.php", false);
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
pauseTime[id].value = JSON.parse(request.responseText);

}
};
request.send(params);
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Listen--------------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Eine Liste wird mit Kundendaten gefüllt und angezeigt----//

function populateListeKunde(data) {

data.forEach(function(item) {
var listItem = document.createElement("li");
listItem.textContent = item;

listItem.addEventListener("contextmenu", function(event) {
event.preventDefault();

var selectedKunde = item;
getCustomerID(selectedKunde, function(selectedID) {
getJob(selectedID, function(job, jobid) {
showSecondList(job, jobid, item);
});
});
});

kundenListe.appendChild(listItem);
});
}

//----Eine zweite Liste wird mit Jobs gefüllt,----//
//----angezeigt und bei Klick auf einen Eintrag---//
//-------die Funktion startTimer aufgerufen-------//

function showSecondList(job, jobid, kundeItem) {

var zweiteListe = document.getElementById("zweiteListe");
zweiteListe.innerHTML = "";

job.forEach(function(item) {
var listItem = document.createElement("li");
listItem.textContent = item;

(function(capturedItem) {
listItem.addEventListener("click", function() {
startTimer(job, jobid, capturedItem, kundeItem);
});
}) (item);
zweiteListe.appendChild(listItem);
});

zweiteListe.style.display = "block";
document.addEventListener('keydown', closeSecondList);
document.addEventListener('click', closeSecondList);
}

//----Nach Klick auf Eintrag wird die Liste geschlossen----//
function closeSecondList() {

var zweiteListe = document.getElementById("zweiteListe");
zweiteListe.style.display = "none";
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Daten speichern-----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Startzeit, -datum, ID und Job werden gespeichert----//

function saveStartTime(user, uhrzeit, datum, endTime, endDate, status, psnr, Job, jobID) {

var method = 'PUT';
var choice = 'start';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&user=" + encodeURIComponent(user) +
"&uhrzeit=" + encodeURIComponent(uhrzeit) +
"&datum=" + encodeURIComponent(datum) +
"&endTime=" + encodeURIComponent(endTime) +
"&endDate=" + encodeURIComponent(endDate) +
"&status=" + encodeURIComponent(status)+
"&psnr=" + encodeURIComponent(psnr)+
"&Job=" + encodeURIComponent(Job)+
"&jobID=" + encodeURIComponent(jobID);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200) {
// Die Antwort ist JSON: {"uid":"..."} - vorher stand die UID als
// nackter Text im Koerper.
sys_uid[zaehler].value = JSON.parse(request.responseText).uid;
}
};
request.send(params);
}

//----Pausezeit wird gespeichert----//

function savePauseTime(pauseTime, id) {

var method = 'PUT';
var choice = 'pause';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&pauseTime=" + encodeURIComponent(pauseTime) +
"&sysuid=" + encodeURIComponent(sys_uid[id].value);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {

if (this.readyState === 4 && this.status === 200) {
// alert(request.responseText);
}
};
request.send(params);
}

//----Stopzeit und -datum wird gespeichert----//

function saveStopTime(stopTimeValue, elapsedTime, elapsedPauseTime, status, uid, vergZeit, comment) {

var method = 'PUT';
var choice = 'stop';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice) +
"&stopTimeValue=" + encodeURIComponent(stopTimeValue) +
"&elapsedTime=" + encodeURIComponent(elapsedTime) +
"&elapsedPauseTime=" + encodeURIComponent(elapsedPauseTime) +
"&status=" + encodeURIComponent(status) +
"&uid=" + encodeURIComponent(uid) +
"&vergZeit=" + encodeURIComponent(vergZeit)+
"&comment=" + encodeURIComponent(comment);

var request = new XMLHttpRequest();

request.open("POST", "saveTime.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200 && timers.length === 0) {
location.reload();
}
};
request.send(params);
}

//-----------------------------------------------------------------------------------------------------------------------//
//---------------------------------------------Like-Suche----------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Durchsucht die Liste der Kunden auf alle einegegebenen Zeichen----//

function searchCustomers(text) {

text = text.toLowerCase();
var kundenListe = document.getElementById("kundenListe");
var listItems = kundenListe.getElementsByTagName("li");

for (i=0; i<listItems.length; i++) {
var item = listItems[i].textContent.toLowerCase();
if (item.includes(text)) {
listItems[i].style.display = "block";
}
else {
listItems[i].style.display = "none";
}
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------Vorhandenen Timer checken----------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Überprüft, ob es Einträge in Datenbank ohne----//
//----Endzeit gibt und startet entsprechend Timer----//

function checkTimer() {

var method = 'POST';
var choice = 'check';

var params = "api_key=" + encodeURIComponent(api_key) +
"&url=" + encodeURIComponent(url) +
"&method=" + encodeURIComponent(method) +
"&choice=" + encodeURIComponent(choice);

var request = new XMLHttpRequest();

request.open("POST", "getData.php");
request.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");

request.onreadystatechange = function() {
if (this.readyState === 4 && this.status === 200 && timers.length === 0) {
var responseData = JSON.parse(request.responseText);

if (responseData.length !== 0) {
startTimeValue = new Date();
var minutes = startTimeValue.getMinutes();
var seconds = startTimeValue.getSeconds();
var month = startTimeValue.getMonth() + 1;

responseData = responseData.toString();
var teile = responseData.split(",");

for (var i=0; i<teile.length; i+=6) {
uhrzeit.push({value: startTimeValue.getHours() + ":" + (minutes < 10 ? "0" + minutes : minutes) + ":" + (seconds < 10 ? "0" + seconds : seconds)});
datum.push({value: startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + startTimeValue.getDate()});

zaehler++;

statusTimer.push({value: 'Running'});
pauseTimers.push({value: 0});
pauseTime.push({value: 0});
timers.push({value: teile[i]});
}

var j=0;
for (var i=1; i<teile.length; i+=6) {
selID.push({value: teile[i]});
getJobs(selID[j].value);
j++;
}

fillArray(2, selectedJob, teile);
fillArray(3, selectedKunde, teile);
fillArray(4, sys_uid, teile);
fillArray(5, startdate, teile);

for (var i=0; i<timers.length; i++) {
var startZeitTeil = timers[i].value.split(":");
var startDatumTeil = startdate[i].value.split(".");

var diffMilli = new Date() - getStartdatum(startDatumTeil, startZeitTeil);
timers[i].value = Math.floor(diffMilli / 1000);
}

selecteID = 0;
startInterval(job);
}
}
};
request.send(params);
}

//----Arrays werden an diese Funktion übergeben und gefüllt----//

function fillArray(LZ, array, teile) {

var arrLZ = 0;
for (var i=LZ; i<teile.length; i+=6) {
array.push({value: teile[i]});
arrLZ++;
}
}

//----Startdatum wird errechnet----//
function getStartdatum(startDatumTeil, startZeitTeil) {

var startdatum = new Date(
parseInt(startDatumTeil[2]),
parseInt(startDatumTeil[1]) -1,
parseInt(startDatumTeil[0]),
parseInt(startZeitTeil[0]),
parseInt(startZeitTeil[1]),
parseInt(startZeitTeil[2])
);
return startdatum;
}

//-----------------------------------------------------------------------------------------------------------------------//
//-------------------------------------------------Interval--------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Interval für Timer wird gestartet----//

function startInterval(job, item, kundeItem, index) {

timerInterval = setInterval(function() {

for (i=0; i<timers.length; i++) {

timers[i].value += 1;
}
updateUI(job, item, kundeItem, index);
}, 1000);
}

//----Interval für Pausentimer wird gestartet----//

function pauseInterval(job, item, kundeItem, id) {

pauseTimerInterval = setInterval(function() {

for (i=0; i<pauseTimers.length; i++) {

pauseTimers[i].value += 1;
}
updateUI(job, item, kundeItem);
}, 1000);
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer starten----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----startTimer bereitet die nötigen Arrays vor,----//
//----speichert Startzeit und -datum,----//
//----beschreibt Arrays und Variablen entsprechend----//
//----und ruft die Funktion saveStartTime auf----//

function startTimer(jobs, jobid, selJob, kundeItem) {

var user = 999;
var endTime = "00:00:00";
var endDate = "0000-00-00";
var status = '01';
zaehler++;

startTimeValue = new Date();

var minutes = startTimeValue.getMinutes();
var seconds = startTimeValue.getSeconds();
uhrzeit.push({value: startTimeValue.getHours() + ":" + (minutes < 10 ? "0" + minutes : minutes) + ":" + (seconds < 10 ? "0" + seconds : seconds)});

var month = startTimeValue.getMonth() + 1;
datum.push({value: startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + startTimeValue.getDate()});

statusTimer.push({value: 'Running'});
pauseTimers.push({value: 0});
pauseTime.push({value: 0});
timers.push({value: 0});
selectedKunde.push({value: kundeItem});
selectedJob.push({value: selJob});
sys_uid.push({value: 0});

var index = jobs.indexOf(selJob);

saveStartTime(user, uhrzeit[zaehler].value, datum[zaehler].value, endTime, endDate, status, selectedID, selJob, jobid[index]);

clearInterval(timerInterval);
startInterval(jobs, selJob, kundeItem, index);

zweiteListe.style.display = "none";
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer stoppen----------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Stopt den Timer, ändert den Status und ruft openLightbox auf----//

function stopTimer(job, item, kundeItem, index, id) {

idStop = id;
statusTimer[id].value = 'Stopped';
openLightbox(job, item, kundeItem, index, id);
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Timer pausieren--------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Pausiert den Timer und ändert den Status----//

function pauseTimer(job, item, kundeItem, id) {

pauseTimers[id].value = 0;
clearInterval(pauseTimerInterval);
pauseInterval(job, item, kundeItem, id);
}

//-----------------------------------------------------------------------------------------------------------------------//
//----------------------------------------------Button Pause-Start-------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Ruft die Funktion pauseTimer oder----//
//----savePauseTimer auf----//

function toggleButton(job, item, kundeItem, id) {

var button = document.getElementById(id);

if (button.innerHTML === "Pause") {

statusTimer[id].value = 'Paused';
pauseTimer(job, item, kundeItem, id);
}
else {

statusTimer[id].value = "Running";
savePauseTime(pauseTimers[id].value, id);
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//------------------------------------------------Ausgabe des Timers-----------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Zeigt eine Liste mit einem oder mehreren----//
//----Timern und Buttons, verteilt dynamisch ID's----//
//----und ruft entsprechend der gedrückten----//
//----Buttons Funktionen auf----//

function updateUI(job, item, kundeItem, index) {
var timerList = document.getElementById("timerList");
timerList.innerHTML = '';

for (i=0; i<timers.length; i++) {
var neueReihe = document.createElement('tr')

//----Name des Kunden wird ausgegeben----//

var kundeEintrag = document.createElement('td');
kundeEintrag.style.position = "fixed";
kundeEintrag.style.top = (12 + i * 14) + "%";
kundeEintrag.style.width = "30%";
kundeEintrag.style.left = "0%";
kundeEintrag.style.textAlign = "center";
kundeEintrag.classList.add('kunde_k');
kundeEintrag.textContent = selectedKunde[i].value;
timerList.appendChild(kundeEintrag);

//----Gewählter Job wird ausgegeben----//

var kontoEintrag = document.createElement('td');
kontoEintrag.style.position = "fixed";
kontoEintrag.style.top = (12 + i * 14) + "%";
kontoEintrag.style.width = "30%";
kontoEintrag.style.left = "30%";
kontoEintrag.style.textAlign = "center";
kontoEintrag.classList.add('konto_k');
kontoEintrag.textContent = selectedJob[i].value;
timerList.appendChild(kontoEintrag);

//----Gestartete Timer werden in Liste----//
//----ausgegeben, pausierte Timer werden----//
//----Liste ausgegeben, sobald Timer gestoppt----//
//----wird Ausgabe in Lightbox----//

if (statusTimer[i].value === "Running") {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(timers[i].value);
timerList.appendChild(laufzeitElement);
}
else if (statusTimer[i].value === 'Paused') {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(pauseTimers[i].value);
timerList.appendChild(laufzeitElement);
}
else if (statusTimer[i].value === 'Stopped') {
var laufzeitElement = document.createElement('td');
laufzeitElement.style.position = "fixed";
laufzeitElement.style.top = (12 + i * 14) + "%";
laufzeitElement.style.width = "15%";
laufzeitElement.style.left = "60%";
laufzeitElement.style.textAlign = "center";
laufzeitElement.classList.add('laufzeit_l');
laufzeitElement.textContent = formatElapsedTime(pauseTimers[i].value);
timerList.appendChild(laufzeitElement);

var zeit = formatElapsedTime(timers[i].value);
zeit = zeit.toString();
var teile = zeit.split(":");

var h = teile[0];
var m = teile[1];
var s = teile[2];

var outStdField = document.getElementById("outStd");
var outMinField = document.getElementById("outMin");
var outSekField = document.getElementById("outSek");

if (document.activeElement !== outStdField && document.activeElement !== outMinField && document.activeElement !== outSekField) {
document.getElementById("outStd").value = h;
document.getElementById("outMin").value = m;
document.getElementById("outSek").value = s;
}

var hEnd = document.getElementById("outStd").value;
var mEnd = document.getElementById("outMin").value;
var sEnd = document.getElementById("outSek").value;
time = hEnd + ":" + mEnd + ":" + sEnd;
}

//----Status (Running, Paused, Stopped) wird ausgegeben----//

var statusTimerElement = document.createElement('td');
statusTimerElement.style.position = "fixed";
statusTimerElement.style.top = (12 + i * 14) + "%";
statusTimerElement.style.width = "15%";
statusTimerElement.style.left = "75%";
statusTimerElement.style.textAlign = "center";
statusTimerElement.classList.add('status_s');
statusTimerElement.textContent = statusTimer[i].value;
timerList.appendChild(statusTimerElement);

//----Pause Button mit dynamisch vergebener ID wird ausgegeben----//

if (statusTimer[i].value === "Running") {
var pauseButton = document.createElement('button')
pauseButton.id = i;
pauseButton.classList.add('pauseButton');
pauseButton.style.position = "fixed";
pauseButton.style.top = (12 + i * 14) + "%";
pauseButton.style.left = "90%";
pauseButton.style.height = "9.4%";
pauseButton.style.minWidth = "3%";
pauseButton.style.fontSize = "80%";
pauseButton.textContent = "Pause"
pauseButton.addEventListener('click', function() {toggleButton(job, item, kundeItem, this.id)});
timerList.appendChild(pauseButton);
}
else if (statusTimer[i].value === "Paused") {
var pauseButton = document.createElement('button')
pauseButton.id = i;
pauseButton.classList.add('pauseButton');
pauseButton.style.position = "fixed";
pauseButton.style.top = (12 + i * 14) + "%";
pauseButton.style.left = "90%";
pauseButton.style.height = "9.4%";
pauseButton.style.minWidth = "3%";
pauseButton.style.fontSize = "80%";
pauseButton.textContent = "Start"
pauseButton.addEventListener('click', function() {toggleButton(job, item, kundeItem, this.id)});
timerList.appendChild(pauseButton);
}

//----Stop Button mit dynamisch vergebener ID wird ausgegeben----//

var stopButton = document.createElement('button')
stopButton.id = i;
stopButton.classList.add('stopButton');
stopButton.style.position = "fixed";
stopButton.style.top = (12 + i * 14) + "%";
stopButton.style.left = "94%";
stopButton.style.height = "9.4%";
stopButton.style.width = "3%";
stopButton.style.fontSize = "80%";
stopButton.textContent = "Stop"
stopButton.addEventListener('click', function() {stopTimer(job, item, kundeItem, index, this.id)});
timerList.appendChild(stopButton);

//----Für jeden aufgerufenen Timer wird----//
//----eine neue Reihe ausgegeben----//

timerList.appendChild(neueReihe);
}
}

//-----------------------------------------------------------------------------------------------------------------------//
//-----------------------------------------------Sekunden in Uhrzeit umrechnen-------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Rechnet übergebene Sekunden in Stunden,----//
//----Minuten und Sekunden und gibt diese----//
//----an aufrufende Funktion zurück----//

function formatElapsedTime(seconds) {

var minutes = Math.floor(seconds / 60);
seconds %= 60;
var hours = Math.floor(minutes / 60);
minutes %= 60;
function addLeadingZero(n) {
return (n < 10 ? '0' : '') + n;
}

return addLeadingZero(hours) + ":" + addLeadingZero(minutes) + ":" + addLeadingZero(seconds);
}

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------Uhrzeit in Sekunden umrechnen----------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Rechnet übergebene Stunden, Minuten----//
//----und Sekunden in Sekunden um und----//
//----gibt diese an aufrufende Funktion zurück----//

function timeInSeconds(zeit) {

var teile = zeit.split(':');
var Stunden = parseInt(teile[0], 10);
var Minuten = parseInt(teile[1], 10);
var Sekunden = parseInt(teile[2], 10);
return Stunden * 3600 + Minuten * 60 + Sekunden;
}

//-----------------------------------------------------------------------------------------------------------------------//
//--------------------------------------------------Lightbox-------------------------------------------------------------//
//-----------------------------------------------------------------------------------------------------------------------//

//----Öffnet eine Lightbox und zeigt Kunde----//
//----Job, vergangene Zeit und evtl Pausenzeit an----//
//----und gibt Möglichkeit alle Zeiten anzupassen----//

function openLightbox(job, item, kundeItem, index, id) {

document.getElementById('lightbox').style.display = 'block';

var dateField = document.getElementById("date");
dateField.value = datum[id].value;
document.getElementById("uhrzeit").innerHTML = uhrzeit[id].value;

var commentTextarea = document.getElementById("comment");
commentTextarea.value = selectedJob[id].value;

document.getElementById("eingPersonZusatz").innerHTML = selectedKunde[id].value;

if (selectedID.length !== undefined) {
document.getElementById("eingPerson").innerHTML = selectedID;
}
else {
document.getElementById("eingPerson").innerHTML = selID[id].value;
}

//----Ausgabe der vergangenen Zeit in Lightbox----//

document.getElementById("outStd").value = 00;
document.getElementById("outMin").value = 00;
document.getElementById("outSek").value = 00;

//----Ausgabe der Pausenzeiten in Lightbox----//

document.getElementById("outStd2").value = 00;
document.getElementById("outMin2").value = 00;
document.getElementById("outSek2").value = 00;
getPauseTime(sys_uid[id].value, id);

var secondsPause = pauseTime[id].value;
secondsPause %= 60;

var minutesPause = Math.floor(pauseTime[id].value / 60);
minutesPause %= 60;

var hoursPause = Math.floor(minutesPause / 60);
hoursPause %= 60;

document.getElementById("outStd2").value = hoursPause;
document.getElementById("outMin2").value = minutesPause;

if (secondsPause > 0) {
document.getElementById("outSek2").value = secondsPause;
}
else {
document.getElementById("outSek2").value = 0;
}

var dropdown2 = document.getElementById("tätigkeit2Dropdown");

job.forEach(function(item, index) {
var option = document.createElement("option");
option.textContent = item;
dropdown2.add(option)

if (item === selectedJob[id].value) {
option.selected = true;
}
});

document.addEventListener('keydown', closeLightboxOnEscape);
document.addEventListener('keydown', closeLightboxOnF2);
}

//----Lightbox schließen----//

function closeLightbox() {

document.getElementById('lightbox').style.display = 'none';
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn der Schließen-Button gedrückt wird----//

function closeLightboxOnSchliessen() {

statusTimer[idStop].value = 'Running';
closeLightbox();
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn Escape gedrückt wird----//

function closeLightboxOnEscape() {

if (event.key === 'Escape') {
statusTimer[idStop].value = 'Running';
closeLightbox();
}
}

//----Funktion closeLightbox wird aufgerufen,----//
//----wenn F2 gedrückt wird----//

function closeLightboxOnF2(event) {

if (event.key === 'F2') {
saveBox();
closeLightbox();
}
}

//----Alle Daten in Lightbox werden gespeichert----//

function saveBox() {

var vergZeit = '"' + time + '"';

var teile = time.split(":");
var stunden = parseInt(teile[0]);
var minuten = parseInt(teile[1]);
var sekunden = parseInt(teile[2]);
time = stunden * 3600 + minuten * 60 + sekunden;

elapsedTime = time;

var comment = '"' + document.getElementById("comment").value + '"';

var hPEnd = document.getElementById("outStd2").value;
var mPEnd = document.getElementById("outMin2").value;
var sPEnd = document.getElementById("outSek2").value;
var pTime = hPEnd + ":" + mPEnd + ":" + sPEnd;
pTime = timeInSeconds(pTime);

var uid = sys_uid[idStop].value;
var month = startTimeValue.getMonth();
var day = startTimeValue.getDate();
month += 1;
var stopTimeValue = '"' + startTimeValue.getFullYear() + "-" + (month < 10 ? "0" + month : month) + "-" + (day < 10 ? "0" + day : day) + '"';

var status = 21;

timers.splice(idStop, 1);
pauseTimers.splice(idStop, 1);
pauseTime.splice(idStop, 1);
selectedKunde.splice(idStop, 1);
selectedJob.splice(idStop, 1);
statusTimer[idStop].value = 'Running';
sys_uid.splice(idStop, 1);

if (zaehler > 0) {
zaehler -= 1;
}

closeLightbox();

if (timers.length === 0) {
clearInterval(timerInterval);
}

saveStopTime(stopTimeValue, elapsedTime, pTime, status, uid, vergZeit, comment);
}

//----Funktion saveBox wird aufgerufen,----//
//----wenn der Save-Button gedrückt wird----//

document.addEventListener('DOMContentLoaded', function() {
const saveButton = document.getElementById('saveButton');
saveButton.addEventListener('click', function() {
saveBox();
})
});
</syntaxhighlight>

= PHP-Script saveTime.php =
<syntaxhighlight lang="php">
<?php
$user = 0;
$uhrzeit = 0;
$datum = 0;
$endTime = 0;
$endDate = 0;
$status = 0;
$psnr = 0;
$comm = 0;
$jobID = 0;
$pauseTime = 0;
$sysuid = 0;
$stopTimeValue = 0;
$elapsedTime = 0;
$elapsedPauseTime = 0;
$status = 0;
$uid = 0;
$vergZeit = 0;

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$api_key = $_POST['api_key'];
$url = $_POST['url'];
$method = $_POST['method'];
$choice = $_POST['choice'];

if (isset($_POST['user'])) {
$user = $_POST['user'];
}
if (isset($_POST['uhrzeit'])) {
$uhrzeit = $_POST['uhrzeit'];
}
if (isset($_POST['datum'])) {
$datum = $_POST['datum'];
}
if (isset($_POST['endTime'])) {
$endTime = $_POST['endTime'];
}
if (isset($_POST['endDate'])) {
$endDate = $_POST['endDate'];
}
if (isset($_POST['status'])) {
$status = $_POST['status'];
}
if (isset($_POST['psnr'])) {
$psnr = $_POST['psnr'];
}
if (isset($_POST['Job'])) {
$comm = $_POST['Job'];
}
if (isset($_POST['jobID'])) {
$jobID = $_POST['jobID'];
}
if (isset($_POST['pauseTime'])) {
$pauseTime = $_POST['pauseTime'];
}
if (isset($_POST['sysuid'])) {
$sysuid = $_POST['sysuid'];
}
if (isset($_POST['stopTimeValue'])) {
$stopTimeValue = $_POST['stopTimeValue'];
}
if (isset($_POST['elapsedTime'])) {
$elapsedTime = $_POST['elapsedTime'];
}
if (isset($_POST['elapsedPauseTime'])) {
$elapsedPauseTime = $_POST['elapsedPauseTime'];
}
if (isset($_POST['status'])) {
$status = $_POST['status'];
}
if (isset($_POST['uid'])) {
$uid = $_POST['uid'];
}
if (isset($_POST['vergZeit'])) {
$vergZeit = $_POST['vergZeit'];
}

$params = array( 'user' => $user,
'uhrzeit' => $uhrzeit,
'datum' => $datum,
'endTime' => $endTime,
'endDate' => $endDate,
'status' => $status,
'psnr' => $psnr,
'comm' => $comm,
'jobID' => $jobID,
'pauseTime' => $pauseTime,
'sysuid' => $sysuid,
'stopTimeValue' => $stopTimeValue,
'elapsedTime' => $elapsedTime,
'elapsedPauseTime' => $elapsedPauseTime,
'status' => $status,
'uid' => $uid,
'vergZeit' => $vergZeit,
'choice' => $choice);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('apikey: '.$api_key));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($curl);

if ($response === false) {
if($error) {
echo "curl_Fehler: ".$error;
}
}
else {
echo $response;
}
}
?>
</syntaxhighlight>

= PHP-Script getData.php =
<syntaxhighlight lang="php">
<?php
$sysuid = 0;
$id = 0;
$selectedKunde = 0;

if ($_SERVER['REQUEST_METHOD'] === 'POST')
{
$api_key = $_POST['api_key'];
$url = $_POST['url'];
$method = $_POST['method'];
$choice = $_POST['choice'];

if (isset($_POST['id'])) {
$id = $_POST['id'];
}
if (isset($_POST['sysuid'])) {
$sysuid = $_POST['sysuid'];
}
if (isset($_POST['selectedKunde'])) {
$selectedKunde = $_POST['selectedKunde'];
}

$params = array( 'sysuid' => $sysuid,
'id' => $id,
'selectedKunde' => $selectedKunde,
'choice' => $choice);

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('apikey: '.$api_key));
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($params));
$response = curl_exec($curl);

if ($response === false) {
if($error) {
echo "curl_Fehler: ".$error;
}
}
else {
echo $response;
}
}
?>
</syntaxhighlight>

= CSS-Datei timestyle.css =
<syntaxhighlight lang="css">
/*-------------------------------------------------------------------------------------------------*/
/*-----------------------------------------Allgemein-----------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

body
{
font-family: 'Arial', sans-serif;
display: flex;
justify-content: right;
align-items: flex-start;
height: 100%;
background-image: url('web_background_3.png');
background-repeat: no-repeat;
background-size: cover;
background-attachment: fixed;
}
ul
{
list-style-type: none;
}
li
{
padding: 0.5em;
cursor: pointer;
display: flex;
justify-content: space-between;
align-items: center;
font-size: 0.85em;
}

/*-------------------------------------------------------------------------------------------------*/
/*-------------------------------------------Suche-------------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

#search
{
position: fixed;
top: 8%;
left: 42%;
width: 15%;
height: 2.8%;
resize: none;
border: 0.04em solid #e4e4e4;
border-radius: 0.1em;
background-color: white;
font-size: 2em;
overflow: hidden;
}

/*-------------------------------------------------------------------------------------------------*/
/*-----------------------------------------Timerausgabe--------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

.kundenliste
{
width: 70%;
height: 30%;
position: fixed;
top: 43.5%;
left: 50%;
transform: translate(-50%, -50%);
border-top-left-radius: 0.2em;
border-top-right-radius: 0.2em;
overflow: auto;
background-color: white;
font-size: 0.85vw;
}
.tabelleUeberschriften
{
width: 70%;
min-height: 3%;
position: fixed;
top: 60%;
left: 50%;
transform: translate(-50%, -50%);
/* border-top: 0.14em solid #ccc;
border-bottom: 0.14em solid #ccc; */
background-color: white;
box-shadow: 0 0px 3px rgba(0, 0, 0, 0.5);
font-size: 0.9vw;
}
#timerList
{
width: 70%;
height: 25%;
position: fixed;
top: 73.5%;
left: 50%;
transform: translate(-50%, -50%);
overflow: auto;
border-bottom-left-radius: 0.2em;
border-bottom-right-radius: 0.2em;
/* border: 0.14em solid red; */
background-color: white;
font-size: 0.85vw;
}
.kunde
{
width: 30%;
position: fixed;
left: 0%;
}
.konto
{
width: 30%;
position: fixed;
left: 30%;
}
.laufzeit
{
width: 15%;
position: fixed;
left: 60%;
}
.status
{
width: 15%;
position: fixed;
left: 75%;
}
.buttons
{
width: 10%;
position: fixed;
left: 90%;
}

/*-------------------------------------------------------------------------------------------------*/
/*-------------------------------------------Lightbox----------------------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

.lightbox
{
display: none;
width: 52%;
height: 62%;
position: fixed;
top: 61.5%;
left: 67%;
border-radius: 0.15em;
background-color: white;
transform: translate(-50%, -50%);
flex-direction: column;
align-items: center;
box-shadow: 0 10px 2000px rgba(0, 0, 0, 0.5);
}

/*-----------------------------------------Lightbox-Inhalt-----------------------------------------*/

.commLabel
{
position: fixed;
top: 5%;
left: 5%;
font-weight: bold;
font-size: 0.8vw;
}
.comment
{
width: 90%;
height: 38%;
position: fixed;
top: 10%;
left: 5%;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.9vw;
}

.bezZeitkonto
{
position: fixed;
top: 55%;
left: 5%;
font-size: 0.8vw;
}
.dropButtonsLightbox
{
width: 37%;
height: 4.4%;
position: fixed;
top: 54%;
left: 15%;
font-size: 0.7vw;
}
.bezDatum
{
position: fixed;
top: 55%;
left: 58%;
font-size: 0.7vw;
}
.date
{
position: fixed;
top: 54%;
left: 68%;
width: 15%;
height: 4%;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
}
.uhrzeit
{
position: fixed;
top: 54%;
left: 85.5%;
width: 10%;
height: 3.9%;
padding: 0.1em;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
resize: none;
}

.bezPerson
{
position: fixed;
top: 68%;
left: 5%;
font-size: 0.8vw;
}
.eingPerson
{
position: fixed;
top: 68%;
left: 15%;
width: 10%;
height: 4.4%;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
}
.eingPersonZusatz
{
position: fixed;
top: 68%;
left: 26%;
width: 25.7%;
height: 4.4%;
overflow: auto;
resize: none;
border: 0.1em solid black;
border-radius: 0.2em;
font-size: 0.8vw;
color: gray;
text-align: center;
}
.Std
{
position: fixed;
top: 63%;
left: 66%;
font-size: 0.7vw;
}
.Min
{
position: fixed;
top: 63%;
left: 78%;
font-size: 0.7vw;
}
.Sek
{
position: fixed;
top: 63%;
left: 91%;
font-size: 0.7vw;
}
.outStd
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 64%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outMin
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 76.5%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outSek
{
width: 6%;
height: 4.4%;
position: fixed;
top: 68%;
left: 89%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}

.Pausenzeiten
{
position: absolute;
top: 79%;
left: 71%;
font-weight: bold;
font-size: 0.8vw;
}
.Std2
{
position: fixed;
top: 84%;
left: 66%;
font-size: 0.7vw;
}
.Min2
{
position: fixed;
top: 84%;
left: 78%;
font-size: 0.7vw;
}
.Sek2
{
position: fixed;
top: 84%;
left: 91%;
font-size: 0.7vw;
}
.outStd2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 64%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outMin2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 76.5%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.outSek2
{
width: 6%;
height: 4.4%;
position: fixed;
top: 89%;
left: 89%;
border: 0.1em solid black;
border-radius: 0.2em;
text-align: center;
font-size: 0.7vw;
}
.saveButton
{
min-width: 8%;
height: 4.4%;
position: fixed;
top: 89%;
left: 5%;
font-size: 0.7vw;
}
.closeButton
{
min-width: 8%;
height: 4.4%;
position: fixed;
top: 89%;
left: 14%;
font-size: 0.7vw;
}

/*-------------------------------------------------------------------------------------------------*/
/*--------------------------------Tätigkeitenliste (zweite Liste)----------------------------------*/
/*-------------------------------------------------------------------------------------------------*/

#zweiteListe
{
display: none;
width: 25%;
max-height: 50%;
position: fixed;
top: 47%;
left: 44%;
padding: 1%;
overflow: auto;
border-radius: 0.2em;
transform: translate(-50%, -50%);
background-color: #FAFAFA;
box-shadow: 0 10px 2000px rgba(0, 0, 0, 0.5);
font-size: 0.85vw;
}

</syntaxhighlight>

OBS/Kostenpflichtige Module/RESTServer/Beispiel1

2026-11-05T12:39:53Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}

=Beispiel 1: Daten-Abruf mit JWT-Authentifizierung=

In diesem Beispiel werden Steuerungs-Variablen aus OBS abgerufen und auf einer Webseite ausgegeben. Der Zugang ist mit JWT-Pflicht eingerichtet, der Konsument muss sich daher zuerst anmelden und einen Token bezogen haben.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' mit Bindung 0.0.0.0:443
* '''Zugang:''' ''Web-Dashboard''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''oauth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
** CORS-Origins: ''https://dashboard.firma.de''
* '''Endpunkt:''' ''steuerung/v1'', dem Profil ''Public-API'' zugeordnet
* '''Berechtigung:''' Zugang ''Web-Dashboard'' für Endpunkt ''steuerung/v1'' freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Wird über die Zugänge-Liste mit '''F7''' geöffnet. Prüfen, ob Benutzername/Passwort gegen die OBS-Benutzerverwaltung passen.

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser : string;
cPass : string;
cSql : string;
qUser : TxFQuery;
lOk : Boolean;
begin
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

cSql := 'SELECT u_nr, u_name FROM benutzer' +
' WHERE u_login = ' + DB_SQLVal(cUser) +
' AND u_passwort_hash = ' + DB_SQLVal(HashPasswort(cPass)) +
' AND u_aktiv = ' + DB_SQLVal('1');

// DB_SOpen liefert true, wenn die ABFRAGE lief - nicht, wenn ein
// Datensatz gefunden wurde. Ohne die EoF-Pruefung wuerde jede
// Anmeldung gelingen, sobald das SQL fehlerfrei ist.
lOk := false;
if (DB_SOpen(oDB, cSql, qUser)) then begin
if (not qUser.EoF) then begin
lOk := true;
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , qUser.A2C('u_nr'));
oWriter.Str('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
oWriter.Str('_OBS_JWT_AUDIENCE', 'dashboard');
end;
end;
DB_Close(qUser);

if (not lOk) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Benutzer oder Passwort ist falsch');
end;
end;
</syntaxhighlight>

{{Hinweis|Hier steht in ''_OBS_JWT_ID'' die Benutzernummer - derselbe Wert also bei
jeder Anmeldung desselben Benutzers. Das ist zulässig: der Server führt seine
Sitzungen über eigene Kennungen (''sid''/''rid''), nicht über das ''jti'' des
Skripts. Mehrfache und parallele Anmeldungen eines Benutzers sind damit
unproblematisch.}}

==Endpunkt-Skript ''steuerung/v1''==

Liefert eine Liste von Steuerungs-Werten zurück. Die Auswertung der JWT-Claims sorgt dafür, dass nur Audience ''dashboard'' Daten erhält.

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Ein Wert als Listeneintrag. Der Helfer bekommt den WRITER und schreibt an
// der Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurueck.
// Der leere Feldname ist der Eintrag einer Liste.
//------------------------------------------------------------------------------

procedure _AddVar(oWriter: TxRestWriter; const cVar: string);
var cTitel : string;
cData : string;
cEinh : string;
lString: Boolean;
lAlign : Boolean;
begin
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin
oWriter.ObjBegin('');
oWriter.Str('variable', cVar);
oWriter.Str('titel' , cTitel);
oWriter.Str('wert' , cData);
oWriter.Str('einheit' , cEinh);
oWriter.ObjEnd;
end;
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// Audience-Pruefung: nur Dashboard-Tokens akzeptieren. Die Ablehnung ist
// ein 403 und keine 200 mit Fehlertext - oWriter.Error baut dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
if (oReader.Param('_OBS_JWT_AUDIENCE') <> 'dashboard') then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt');
exit;
end;

// Die Antwort ist eine nackte Liste, kein Objekt: RootArr sagt das, und
// zwar VOR dem ersten Eintrag. Ein ArrEnd gibt es dazu nicht - die
// Wurzelklammer setzt der Server.
oWriter.RootArr();
_AddVar(oWriter, 'WERT_1');
_AddVar(oWriter, 'WERT_2');
_AddVar(oWriter, 'WERT_3');
_AddVar(oWriter, 'WERT_4');
end;
</syntaxhighlight>

==JavaScript-Client (Browser)==

Im Browser werden zwei Aufrufe gemacht: erst Token holen, dann Daten lesen.

<syntaxhighlight lang="javascript" line>
const API_BASE = 'https://api.meinserver.de';
const API_KEY = '[API-KEY]';

async function login(username, password) {
const res = await fetch(`${API_BASE}/oauth/`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY },
body: JSON.stringify({ username, password })
});
if (!res.ok) throw new Error('Login fehlgeschlagen');
const data = await res.json();
return data.token;
}

async function ladeSteuerung(token) {
const res = await fetch(`${API_BASE}/steuerung/v1`, {
method: 'GET',
headers: {
'apikey': API_KEY,
'Authorization': 'Bearer ' + token
}
});
if (!res.ok) throw new Error('Abruf fehlgeschlagen: ' + res.status);
return res.json();
}

async function zeigeTabelle() {
const token = await login('mitarbeiter', 'geheim');
const werte = await ladeSteuerung(token);

const tbl = document.getElementById('steuerung');
werte.forEach(w => {
const tr = document.createElement('tr');
tr.innerHTML = `<td>${w.titel}</td><td>${w.wert} ${w.einheit}</td>`;
tbl.appendChild(tr);
});
}

zeigeTabelle();
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"mitarbeiter\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/oauth/

Antwort:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 3600,
"serverTime": "2026-08-19T09:12:33+02:00"}

Da das Skript kein ''_OBS_JWT_REFRESH_ID'' liefert, enthält die Antwort kein
''refreshToken'' - der Client meldet sich nach Ablauf der 60 Minuten neu an.

Daten abrufen:

curl -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJhbGciOi..." ^
https://api.meinserver.de/steuerung/v1

==Was zeigt das Beispiel?==

* Zweistufige Anmeldung: API-Key + JWT.
* Sichere Trennung von Konsumenten-Gruppen über die Audience-Claim.
* Eigenes Authentifizierungs-Skript pro Zugang.
* Browser-Zugriff über CORS-erlaubtes Origin.
* Anmeldung ohne Refresh-Token: einfachster Fall, der Token läuft nach der Zeit aus ''JWT-Exp'' ab.

OBS/Kostenpflichtige Module/RESTServer

2026-11-05T12:39:52Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

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.

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

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''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===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''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)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''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)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''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.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''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.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''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:

{| 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-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| 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:

# 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"
! Anfrage !! Antwort
|-
| <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
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
|-
| Gepackter Körper bei einem Datei-Upload || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
|-
| Entpackter Körper über '''10 MB''' || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|}

{{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:

* '''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"
! Grenze !! Wert !! Bedeutung
|-
| Leerlauf || '''10 Sekunden''' || Passiert auf der Verbindung so lange nichts, wird sie geschlossen
|-
| Anfragen je Verbindung || '''100''' || Danach schliesst der Server geordnet, der Client baut neu auf
|}

Beides ist für den Konsumenten unkritisch: Eine geschlossene Verbindung ist kein
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 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 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:

* 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"
! Befehl !! Wirkung
|-
| ''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
|-
| ''1'' … ''9'' || Auswahl im Kopfbereich - kürzer als ''show'' für die gerade sichtbaren Anfragen. Mit ''mouse on'' auch per Klick
|-
| ''ps'' || Listet die gerade laufenden Anfragen auf
|-
| ''level <stufe>'' || Anzeigestufe des Live-Logs: ''quiet'' , ''normal'' oder ''debug''. Ohne Parameter wird die aktuelle Stufe genannt
|-
| ''filter <ausdruck>'' || Blendet aus, was nicht passt: ''path=<text>'', ''account=<name>'', ''status>=<code>''. ''filter aus'' hebt die Einschränkung auf
|-
| ''panel on|off'' || Fixierten Kopfbereich ein-/ausschalten. '''Ausgeschaltet''' lässt sich der Rückblick-Puffer des Konsolenfensters wieder scrollen
|-
| ''mouse on|off'' || Klick-Auswahl im Kopfbereich. '''Eingeschaltet''' ist das Markieren von Text mit der Maus nicht mehr möglich
|-
| ''help'' / ''?'' || Zeigt diese Liste in der Konsole
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

{{Hinweis|Der Anzeigefilter wirkt '''nur auf die Anzeige'''. Was die Konsole
ausblendet, steht vollständig in RESTSRV_PROTO - es geht nichts verloren.}}

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

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]] - Portfreigabe, Reverse-Proxy oder VPN im Vergleich
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] - automatische Zertifikate über http-01 oder dns-01
* [[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/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[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]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-11-05T12:39:52Z

MINERVA-Rademacker: Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]

{{Vorlage:Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|automatische Zertifikatserneuerung]]. Wie der Server von aussen erreichbar wird und welche Variante sich eignet, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Betrieb hinter einem Reverse-Proxy==

Soll der Server des REST-Dienstes nicht direkt aus dem Internet erreichbar sein, nimmt ein Reverse-Proxy die Anfragen entgegen, zum Beispiel in einer DMZ oder als Funktion der Firewall, und reicht sie an den REST-Dienst weiter. Von aussen ist nur der Proxy erreichbar. Vor- und Nachteile gegenüber Portfreigabe und VPN beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

Am Proxy und im Netz richten Sie ein:

* '''Öffentlicher Name:''' zeigt auf die öffentliche IP-Adresse des Proxys.
* '''Zertifikat:''' Der Proxy braucht ein öffentlich gültiges Zertifikat für diesen Namen. Die automatische Zertifikatserneuerung des REST-Servers wird nicht benötigt.
* '''Weiterleitung:''' Der Proxy leitet per HTTPS an <code>https://<Server des REST-Dienstes>:<Port></code> weiter. Für diese Strecke genügt am REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut. Auch dieses Zertifikat läuft ab und muss vor Ablauf getauscht werden.
* '''Header:''' Alle HTTP-Methoden und Header unverändert durchreichen, insbesondere ''Authorization'', ''apikey'' und ''Idempotency-Key''. Antworten nicht zwischenspeichern. Den Header ''X-Forwarded-For'' mit der IP-Adresse des Konsumenten setzen.
* '''Anfragegrösse:''' Die maximale Anfragegrösse am Proxy darf nicht unter der Upload-Grenze der Endpunkte liegen.
* '''Firewall:''' Den Port des REST-Servers intern nur für den Proxy freigeben.

Hinter dem Proxy verhält sich der REST-Server so:

* Protokoll und Konsole zeigen als Host die IP-Adresse des Proxys und hängen den Wert von ''X-Forwarded-For'' als <code>[xff=…]</code> an.
* Die [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]] eines Zugangs kann keine einzelnen Konsumenten unterscheiden.
* Beim [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Rate-Limit je Profil|Rate-Limit]] teilen sich alle Konsumenten ohne API-Key einen Zähler.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe

2026-10-26T10:31:32Z

MINERVA-Rademacker: Vergleichstabelle: selbst signiertes Zertifikat zwischen Proxy und REST-Server genannt [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Übersicht}}
= Öffentliche Freigabe =

Apps auf mobilen Geräten und externe Systeme erreichen den REST-Server nur, wenn er aus dem Internet erreichbar ist. Diese Seite stellt die drei Wege dafür gegenüber und richtet sich an die IT-Administration, die über die Freigabe entscheidet.

{{Hinweis|Der REST-Dienst läuft auf dem OBS-Server oder auf einem [[#REST-Dienst auf einem eigenen Server|eigenen Server]]. Auf dem OBS-Server läuft häufig auch die Datenbank. Die Varianten unterscheiden sich vor allem darin, ob eine Verbindung aus dem Internet den Server des REST-Dienstes direkt erreicht. Ein Zertifikat ist in allen Varianten nötig, auch im VPN, weil die App nur per HTTPS verbindet.}}

== Varianten im Vergleich ==
{| class="wikitable"
! Merkmal !! Direkte Portfreigabe !! Reverse-Proxy !! VPN
|-
| Aus dem Internet erreichbar || Server des REST-Dienstes: Port des REST-Servers, bei Prüfart http-01 zusätzlich Port 80 || nur der Proxy (Port 443) || nur das VPN-Gateway
|-
| Aufwand für die Nutzer der App || keiner || keiner || VPN-Client einrichten und vor der Nutzung einschalten
|-
| Aufwand für die IT || Portweiterleitung am Router || Proxy betreiben, Zertifikat am Proxy || VPN-Zugang für jedes Gerät
|-
| Filtern und Protokollieren vor dem REST-Dienst || – || ✓ || nur auf Netzebene
|-
| Zertifikat || im REST-Server, Prüfart http-01 oder dns-01 || öffentlich am Proxy, dazu eines im REST-Server für die Strecke vom Proxy (selbst signiert genügt) || im REST-Server, Prüfart dns-01
|-
| REST-Server sieht die IP-Adresse des Geräts || ✓ || nur im Protokoll (über ''X-Forwarded-For'') || ✓, sofern das VPN-Gateway die Adressen nicht umsetzt (NAT)
|}

== Schutz durch den REST-Server ==
Unabhängig von der Variante schützt sich der REST-Server selbst. Diese Mechanismen greifen in allen drei Varianten:
* '''Verschlüsselung:''' ausschliesslich TLS 1.2 mit Forward Secrecy und AEAD-Verfahren. Unverschlüsselte Anfragen an einen TLS-Port werden vor jeder Verarbeitung abgewiesen. Optional mTLS: jeder Client braucht ein gültiges Client-Zertifikat.
* '''Zugänge:''' Jede Anfrage braucht einen gültigen API-Key, wahlweise zusätzlich JWT. Jeder Zugang ist nur für die Endpunkte freigeschaltet, die er braucht, und lässt sich auf eine Absenderadresse beschränken. API-Keys lassen sich ohne Unterbrechung tauschen.
* '''Widerrufbare Sitzungen:''' Eine Abmeldung wirkt sofort. Ein Refresh-Token gilt genau einmal; wird ein verbrauchtes erneut vorgelegt, sperrt der Server die ganze Sitzung.
* '''Grenzen gegen Missbrauch:''' getrenntes Rate-Limit für erfolgreiche und fehlgeschlagene Anfragen, eine Obergrenze gleichzeitiger Anfragen und Verbindungen sowie Grössengrenzen für Anfragen und Uploads.
* '''Keine Informationen nach aussen:''' Fehlerantworten enthalten nie interne Details. Die stehen nur im Protokoll, mit einer Korrelations-ID je Anfrage. Kennwörter und Token werden dort maskiert.
* '''Kurze Öffnung für die Zertifikatsprüfung:''' Bei http-01 öffnet der Dienst Port 80 nur für die Dauer der Prüfung.

Diese Mechanismen schützen den REST-Dienst. Reverse-Proxy und VPN fügen eine Schicht davor hinzu: Sie halten den Server des REST-Dienstes aus dem Internet heraus, und mit ihm häufig auch den OBS-Server und die Datenbank. Das wirkt auch gegen Schwachstellen ausserhalb des REST-Servers und gegen Überlastung.
Der Router leitet den Port des REST-Servers aus dem Internet auf den Server des REST-Dienstes weiter. Für die Zertifikatserneuerung mit der Prüfart http-01 wird zusätzlich Port 80 weitergeleitet.

'''Vorteile'''
* Die einfachste Einrichtung, es wird keine weitere Komponente gebraucht.
* Die App funktioniert überall, ohne dass die Nutzer etwas tun müssen.
* Der REST-Server sieht die IP-Adresse jedes Geräts. Alle Schutzmechanismen des REST-Servers, auch Host-Beschränkung und Rate-Limit, arbeiten damit je Gerät.

'''Nachteile'''
* Der Server des REST-Dienstes ist direkt aus dem Internet erreichbar. Läuft der REST-Dienst auf dem OBS-Server, gilt das für den OBS-Server und häufig auch für die Datenbank. Die [[#Schutz durch den REST-Server|Schutzmechanismen des REST-Servers]] greifen, eine zusätzliche Schicht davor gibt es aber nicht.
* Mit der Prüfart http-01 ist zusätzlich Port 80 weitergeleitet. Mit der Prüfart dns-01 entfällt das.

== Reverse-Proxy ==
Ein Reverse-Proxy, zum Beispiel in einer DMZ oder als Funktion der Firewall, nimmt HTTPS auf Port 443 an. Er prüft die Anfrage und reicht sie über eine eigene, ebenfalls verschlüsselte Verbindung an den REST-Server weiter.

'''Vorteile'''
* Der Server des REST-Dienstes ist aus dem Internet nicht erreichbar, nur der Proxy.
* Am Proxy lassen sich Anfragen nach Ihren Vorgaben filtern, drosseln und protokollieren.
* Für die Nutzer der App ändert sich nichts.
* Das öffentliche Zertifikat liegt am Proxy. Für die Strecke vom Proxy genügt im REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes. Es muss vor Ablauf getauscht werden.

'''Nachteile'''
* Der Proxy muss betrieben und gepflegt werden.
* Der REST-Server sieht als Absender nur den Proxy. Die Host-Beschränkung eines Zugangs kann keine Geräte unterscheiden, und Anfragen ohne API-Key teilen sich einen Zähler des Rate-Limits. Die IP-Adresse des Geräts steht nur im Protokoll, wenn der Proxy den Header ''X-Forwarded-For'' setzt.

Die Einrichtung beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].

== VPN ==
Die Geräte verbinden sich per VPN mit dem Netz, in dem der REST-Dienst läuft. Die App spricht durch den Tunnel per HTTPS mit dem REST-Server. Aus dem Internet ist nur das VPN-Gateway erreichbar.

'''Vorteile'''
* Für den REST-Server ist kein Port aus dem Internet offen.
* Nur Geräte mit VPN-Zugang erreichen den REST-Server.
* Setzt das VPN-Gateway die Adressen nicht um, sieht der REST-Server die VPN-Adresse jedes Geräts.

'''Nachteile'''
* Jedes Gerät braucht einen VPN-Client und einen eigenen Zugang. Ohne zentrale Geräteverwaltung schalten die Nutzer das VPN von Hand ein. Ist es aus, meldet die App, dass der Server nicht erreichbar ist.
* Ein VPN-Zugang öffnet den Weg ins Netz. Beschränken Sie ihn auf die Adresse und den Port des REST-Servers.
* Das Zertifikat lässt sich nur mit der Prüfart dns-01 erneuern, weil die Zertifizierungsstelle den Server nicht erreicht.
* Der Name des REST-Servers muss auf dem Gerät auf die interne Adresse zeigen. Das geht über einen DNS-Server, den das VPN mitliefert, oder über einen öffentlichen DNS-Eintrag mit der internen Adresse. Manche Router verwerfen solche Antworten als Schutz gegen DNS-Rebinding; dann löst der Name in diesem Netz nicht auf.

Das Zertifikat richten Sie wie unter [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] beschrieben mit der Prüfart dns-01 ein.

== REST-Dienst auf einem eigenen Server ==
Der REST-Dienst muss nicht auf dem OBS-Server laufen. Er lässt sich auch auf einem eigenen Server betreiben, zum Beispiel in einer DMZ. Voraussetzung ist, dass dieser Server
* per SMB auf den OBS-Server zugreifen kann und
* die Datenbank erreicht.

Der eigene Server lässt sich mit jeder der drei Varianten kombinieren. Bei der direkten Portfreigabe zeigt die Weiterleitung dann auf diesen Server statt auf den OBS-Server.

'''Vorteile'''
* Eine Verbindung aus dem Internet erreicht weder den OBS-Server noch die Datenbank direkt, auch bei direkter Portfreigabe.
* Die Verarbeitung der Anfragen läuft nicht auf dem OBS-Server. Die Datenbank wird weiterhin belastet.

'''Nachteile'''
* Ein weiterer Server muss betrieben und gepflegt werden.
* Vom eigenen Server ins interne Netz müssen SMB und der Port der Datenbank offen sein. Beschränken Sie diese Wege auf den OBS-Server und den Datenbankserver.

== Entscheidungshilfe ==
* '''Keine eingehende Verbindung zum OBS-Server erlaubt, DMZ oder Firewall mit Proxy-Funktion vorhanden:''' Reverse-Proxy.
* '''Keine eingehende Verbindung zum OBS-Server erlaubt, aber kein Proxy vorhanden:''' REST-Dienst auf einem eigenen Server in einer DMZ, mit direkter Portfreigabe auf diesen Server.
* '''Geräte werden zentral verwaltet oder ein VPN ist ohnehin im Einsatz:''' VPN.
* '''Kleine Installation ohne Vorgaben der IT:''' Direkte Portfreigabe, möglichst mit der Prüfart dns-01, damit Port 80 geschlossen bleibt.

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]]

OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung

2026-10-26T10:31:32Z

MINERVA-Rademacker: Reverse-Proxy: selbst signiertes Zertifikat für die Strecke zum REST-Server genannt [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Zertifikatserneuerung =

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

{{Hinweis|Jedes Server-Profil braucht im Betrieb ein Zertifikat, auch hinter einem Reverse-Proxy und im VPN: Eine App verbindet sich ausschliesslich per HTTPS, und ohne Zertifikat startet das Profil nicht. ''kein SSL'' ist nur für lokale Tests gedacht. Das Zertifikat beziehen Sie entweder automatisch wie hier beschrieben, oder Sie hinterlegen es von Hand im Server-Profil und tauschen es vor Ablauf.}}

{{Auf einen Blick|1=
* '''Zwei Prüfarten.''' http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
* '''Selbsttest vorab.''' Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
* '''Erneuerung ab 30 Tagen Restlaufzeit.''' Das bisherige Zertifikat bleibt als Rückfall erhalten.
* '''dns-01 braucht nur ausgehende Verbindungen''' und eignet sich damit für VPN und für Server ohne Portfreigabe.
}}

== Voraussetzungen ==
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.firma.de''. Platzhalter-Zertifikate (''*.firma.de'') werden nicht unterstützt.
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL'''.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>).
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

=== Welche Prüfart? ===
{| class="wikitable"
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss
|-
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist || Port 80
|-
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts
|}

Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|öffentlichen Freigabe]] passt:
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy. Der REST-Server braucht trotzdem ein Zertifikat für die Strecke vom Proxy. Dafür genügt ein selbst signiertes Zertifikat oder eines Ihrer internen Zertifizierungsstelle, sofern der Proxy ihm vertraut. Es wird im Server-Profil hinterlegt und muss vor Ablauf getauscht werden.
* '''VPN:''' dns-01.

=== Wege bei dns-01 ===
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag <code>_acme-challenge.<Name></code> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

{| class="wikitable"
! Weg !! Wann !! Einmalig beim DNS des Namens !! Einstellung '''DNS-Anbieter'''
|-
| Direkt beim Anbieter || Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS || nichts, Sie brauchen nur ein API-Token || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf eine Zone bei einem Anbieter || Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen || CNAME <code>_acme-challenge.<Name></code> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf acme-dns || Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister || CNAME <code>_acme-challenge.<Name></code> auf die ''fulldomain'' des acme-dns-Kontos || ''acme-dns''
|}

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

{{Hinweis|Nutzen Sie einen DNS-Anbieter, der hier nicht aufgeführt ist, wenden Sie sich an den OBS-Support. Bietet der Anbieter eine Schnittstelle (API) für DNS-Einträge, ist eine Anbindung in der Regel möglich. Bis dahin funktioniert der CNAME-Weg mit jedem Anbieter.}}

{{Hinweis|Namen von DynDNS-Diensten (zum Beispiel ''…myfritz.net'') eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.}}

== Vorgehen ==
=== Gemeinsame Einstellungen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server → Server''' und öffnen Sie das Server-Profil.
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''.
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll.
# Tragen Sie unter '''Kontakt bei der CA''' eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
# Richten Sie die Registerkarte '''5 DNS-Prüfung''' nach einem der folgenden Abschnitte ein und speichern Sie.
# Starten Sie den REST-Dienst neu.
}}

=== Prüfart http-01 ===
{{Schritte|1=
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
# Leiten Sie am Router Port 80 von aussen auf den Server des REST-Dienstes weiter.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer.
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein.
}}

Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

=== Prüfart dns-01 direkt beim DNS-Anbieter ===
{{Schritte|1=
# Erstellen Sie beim Anbieter der Zone ein API-Token:
#* '''Hetzner:''' ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
#* '''Cloudflare:''' ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
#* '''IONOS:''' einen API-Schlüssel. Er besteht aus Präfix und Secret.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''dns-01 (DNS-Eintrag)'' und im Feld '''DNS-Anbieter''' den Anbieter.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein, bei IONOS in der Form <code>Präfix.Secret</code>.
# Lassen Sie '''Name des TXT-Eintrags''' leer.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter ===
{{Schritte|1=
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs-firma.acme.example.de''. Einen Eintrag müssen Sie dort nicht anlegen.
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.firma.de</code> auf ''obs-firma.acme.example.de''.
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein.
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs-firma.acme.example.de''.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf acme-dns ===
{{Schritte|1=
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den DNS-Anbieter ''acme-dns''.
# Tragen Sie unter '''Adresse (acme-dns)''' die Adresse der Instanz ein. Sie beginnt mit <code>https://</code>.
# Lassen Sie '''Benutzer (acme-dns)''', '''Schlüssel / API-Token''' und '''Name des TXT-Eintrags''' leer und speichern Sie.
# Geben Sie in der Konsole <code>cert test</code> ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter '''Letzte Meldung''' steht danach der CNAME, den Sie anlegen müssen.
# Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: <code>_acme-challenge.<Name></code> auf die genannte ''fulldomain''.
# Geben Sie in der Konsole erneut <code>cert test</code> ein.
}}

{{Achtung|Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen ''fulldomain'' anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.}}

=== Erstes Zertifikat holen ===
Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

=== Testbetrieb ===
{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

== Ergebnis ==
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Unter '''Letzte Meldung''' steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt '''Zertifikat gültig bis''' das Ablaufdatum, und <code>cert</code> in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht.
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld '''Gesperrt bis''' zeigt, bis wann. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre.

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

== Wenn es nicht klappt ==
Die Meldungen stehen unter '''Letzte Meldung''' und im Protokoll des REST-Servers.

{| class="wikitable"
! Meldung !! Ursache
|-
| "Port 80 laesst sich nicht oeffnen - er ist belegt" || Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
|-
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt
|-
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer
|-
| "acme-dns: Konto unvollstaendig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
|-
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
|-
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben
|-
| "IONOS: keine Zone zu … im Vertrag des Schluessels" || Der API-Schlüssel gehört zu einem anderen Vertrag
|-
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern
|-
| "… ist nach 210 Sekunden noch nicht ueberall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus
|-
| "kein oeffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
|-
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein
|}

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Automatische Zertifikatserneuerung|Server-Profile: Felder der Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung

2026-10-26T10:23:15Z

MINERVA-Rademacker: Hinweis: nicht aufgeführte DNS-Anbieter über den OBS-Support [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Zertifikatserneuerung =

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

{{Hinweis|Jedes Server-Profil braucht im Betrieb ein Zertifikat, auch hinter einem Reverse-Proxy und im VPN: Die App verbindet sich ausschliesslich per HTTPS, und ohne Zertifikat startet das Profil nicht. ''kein SSL'' ist nur für lokale Tests gedacht. Das Zertifikat beziehen Sie entweder automatisch wie hier beschrieben, oder Sie hinterlegen es von Hand im Server-Profil und tauschen es vor Ablauf.}}

{{Auf einen Blick|1=
* '''Zwei Prüfarten.''' http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
* '''Selbsttest vorab.''' Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
* '''Erneuerung ab 30 Tagen Restlaufzeit.''' Das bisherige Zertifikat bleibt als Rückfall erhalten.
* '''dns-01 braucht nur ausgehende Verbindungen''' und eignet sich damit für VPN und für Server ohne Portfreigabe.
}}

== Voraussetzungen ==
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.firma.de''. Platzhalter-Zertifikate (''*.firma.de'') werden nicht unterstützt.
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL'''.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>).
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

=== Welche Prüfart? ===
{| class="wikitable"
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss
|-
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist || Port 80
|-
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts
|}

Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|öffentlichen Freigabe]] passt:
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy. Der REST-Server braucht trotzdem ein Zertifikat für die Strecke vom Proxy, zum Beispiel von Ihrer internen Zertifizierungsstelle. Es wird im Server-Profil hinterlegt und muss vor Ablauf getauscht werden.
* '''VPN:''' dns-01.

=== Wege bei dns-01 ===
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag <code>_acme-challenge.<Name></code> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

{| class="wikitable"
! Weg !! Wann !! Einmalig beim DNS des Namens !! Einstellung '''DNS-Anbieter'''
|-
| Direkt beim Anbieter || Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS || nichts, Sie brauchen nur ein API-Token || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf eine Zone bei einem Anbieter || Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen || CNAME <code>_acme-challenge.<Name></code> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf acme-dns || Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister || CNAME <code>_acme-challenge.<Name></code> auf die ''fulldomain'' des acme-dns-Kontos || ''acme-dns''
|}

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

{{Hinweis|Nutzen Sie einen DNS-Anbieter, der hier nicht aufgeführt ist, wenden Sie sich an den OBS-Support. Bietet der Anbieter eine Schnittstelle (API) für DNS-Einträge, ist eine Anbindung in der Regel möglich. Bis dahin funktioniert der CNAME-Weg mit jedem Anbieter.}}

{{Hinweis|Namen von DynDNS-Diensten (zum Beispiel ''…myfritz.net'') eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.}}

== Vorgehen ==
=== Gemeinsame Einstellungen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server → Server''' und öffnen Sie das Server-Profil.
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''.
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll.
# Tragen Sie unter '''Kontakt bei der CA''' eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
# Richten Sie die Registerkarte '''5 DNS-Prüfung''' nach einem der folgenden Abschnitte ein und speichern Sie.
# Starten Sie den REST-Dienst neu.
}}

=== Prüfart http-01 ===
{{Schritte|1=
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
# Leiten Sie am Router Port 80 von aussen auf den Server des REST-Dienstes weiter.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer.
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein.
}}

Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

=== Prüfart dns-01 direkt beim DNS-Anbieter ===
{{Schritte|1=
# Erstellen Sie beim Anbieter der Zone ein API-Token:
#* '''Hetzner:''' ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
#* '''Cloudflare:''' ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
#* '''IONOS:''' einen API-Schlüssel. Er besteht aus Präfix und Secret.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''dns-01 (DNS-Eintrag)'' und im Feld '''DNS-Anbieter''' den Anbieter.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein, bei IONOS in der Form <code>Präfix.Secret</code>.
# Lassen Sie '''Name des TXT-Eintrags''' leer.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter ===
{{Schritte|1=
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs-firma.acme.example.de''. Einen Eintrag müssen Sie dort nicht anlegen.
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.firma.de</code> auf ''obs-firma.acme.example.de''.
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein.
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs-firma.acme.example.de''.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf acme-dns ===
{{Schritte|1=
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den DNS-Anbieter ''acme-dns''.
# Tragen Sie unter '''Adresse (acme-dns)''' die Adresse der Instanz ein. Sie beginnt mit <code>https://</code>.
# Lassen Sie '''Benutzer (acme-dns)''', '''Schlüssel / API-Token''' und '''Name des TXT-Eintrags''' leer und speichern Sie.
# Geben Sie in der Konsole <code>cert test</code> ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter '''Letzte Meldung''' steht danach der CNAME, den Sie anlegen müssen.
# Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: <code>_acme-challenge.<Name></code> auf die genannte ''fulldomain''.
# Geben Sie in der Konsole erneut <code>cert test</code> ein.
}}

{{Achtung|Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen ''fulldomain'' anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.}}

=== Erstes Zertifikat holen ===
Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

=== Testbetrieb ===
{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

== Ergebnis ==
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Unter '''Letzte Meldung''' steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt '''Zertifikat gültig bis''' das Ablaufdatum, und <code>cert</code> in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht.
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld '''Gesperrt bis''' zeigt, bis wann. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre.

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

== Wenn es nicht klappt ==
Die Meldungen stehen unter '''Letzte Meldung''' und im Protokoll des REST-Servers.

{| class="wikitable"
! Meldung !! Ursache
|-
| "Port 80 laesst sich nicht oeffnen - er ist belegt" || Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
|-
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt
|-
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer
|-
| "acme-dns: Konto unvollstaendig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
|-
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
|-
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben
|-
| "IONOS: keine Zone zu … im Vertrag des Schluessels" || Der API-Schlüssel gehört zu einem anderen Vertrag
|-
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern
|-
| "… ist nach 210 Sekunden noch nicht ueberall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus
|-
| "kein oeffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
|-
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein
|}

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Automatische Zertifikatserneuerung|Server-Profile: Felder der Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-10-26T10:21:58Z

MINERVA-Rademacker: Reverse-Proxy: internes Zertifikat läuft ab und muss getauscht werden [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|automatische Zertifikatserneuerung]]. Wie der Server von aussen erreichbar wird und welche Variante sich eignet, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Betrieb hinter einem Reverse-Proxy==

Soll der Server des REST-Dienstes nicht direkt aus dem Internet erreichbar sein, nimmt ein Reverse-Proxy die Anfragen entgegen, zum Beispiel in einer DMZ oder als Funktion der Firewall, und reicht sie an den REST-Dienst weiter. Von aussen ist nur der Proxy erreichbar. Vor- und Nachteile gegenüber Portfreigabe und VPN beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

Am Proxy und im Netz richten Sie ein:

* '''Öffentlicher Name:''' zeigt auf die öffentliche IP-Adresse des Proxys.
* '''Zertifikat:''' Der Proxy braucht ein öffentlich gültiges Zertifikat für diesen Namen. Die automatische Zertifikatserneuerung des REST-Servers wird nicht benötigt.
* '''Weiterleitung:''' Der Proxy leitet per HTTPS an <code>https://<Server des REST-Dienstes>:<Port></code> weiter. Für diese Strecke genügt am REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut. Auch dieses Zertifikat läuft ab und muss vor Ablauf getauscht werden.
* '''Header:''' Alle HTTP-Methoden und Header unverändert durchreichen, insbesondere ''Authorization'', ''apikey'' und ''Idempotency-Key''. Antworten nicht zwischenspeichern. Den Header ''X-Forwarded-For'' mit der IP-Adresse des Konsumenten setzen.
* '''Anfragegrösse:''' Die maximale Anfragegrösse am Proxy darf nicht unter der Upload-Grenze der Endpunkte liegen.
* '''Firewall:''' Den Port des REST-Servers intern nur für den Proxy freigeben.

Hinter dem Proxy verhält sich der REST-Server so:

* Protokoll und Konsole zeigen als Host die IP-Adresse des Proxys und hängen den Wert von ''X-Forwarded-For'' als <code>[xff=…]</code> an.
* Die [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]] eines Zugangs kann keine einzelnen Konsumenten unterscheiden.
* Beim [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Rate-Limit je Profil|Rate-Limit]] teilen sich alle Konsumenten ohne API-Key einen Zähler.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-10-26T10:21:58Z

MINERVA-Rademacker: Modi: Standard-TLS gilt für jeden Betrieb, nicht nur im öffentlichen Netz [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| zusätzliche Infos || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS-Modus aktiv || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Zertifikat (cert) || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Schlüssel (key) || PEM-Inhalt des privaten Schlüssels
|-
| Root-Zertifikat (ca) || PEM-Inhalt des CA-Zertifikats, gegen das '
|-
| Rate-Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Erfolgsanfragen || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Fehlanfragen || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Anfragen || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| max. Anfragen || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|-
| keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
|}

{{Hinweis|''max. Verbindungen'' und ''max. Anfragen'' sind die beiden
'''Lastgrenzen''' des Profils. Davon zu unterscheiden sind die festen Grenzen der
persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -,
die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe
[[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Persistente
Verbindungen.}}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Zertifikat + Schlüssel || Für den Betrieb, auch wenn der Server nur intern, hinter einem Reverse-Proxy oder per VPN erreichbar ist
|-
| '''mTLS''' || Zertifikat + Schlüssel + Root-Zert. || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''HSTS:''' Jede Antwort eines TLS-Profils trägt ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse damit ein Jahr lang nur noch über HTTPS an. Beim Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
* '''Rotation:''' Bei '''automatischer Erneuerung''' tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
==Automatische Zertifikatserneuerung==

Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Prüfarten, Voraussetzungen, Einrichtung, Ablauf und Konsolenbefehle beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]].

===Felder===

Registerkarte '''4 Zertifikaterneuerung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Automatische Erneuerung || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = nur für Testsysteme, siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Testbetrieb|Testbetrieb]]
|-
| Zertifikatsname (FQDN) || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
|-
| Kontakt bei der CA || Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
|-
| Zertifikat gültig bis || Ablaufdatum des aktiven Zertifikats
|-
| Testzertifikat aus Staging || Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
|-
| Zustand || ''idle'' = nichts zu tun, ''pending'' = Vorgang läuft, ''error'' = letzter Versuch fehlgeschlagen
|-
| Letzte Meldung || Ergebnis des letzten Vorgangs - im Störungsfall das erste Feld, in das Sie sehen
|-
| Gesperrt bis || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
|-
| Letzter Selbsttest am || Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle
|-
| Selbsttest bestanden || Ergebnis dieser Prüfung
|}

Die Felder ab ''Zertifikat gültig bis'' füllt der Dienst selbst; sie dienen der Anzeige.

Registerkarte '''5 DNS-Prüfung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Prüfart || ''http-01 (Port 80)'' oder ''dns-01 (DNS-Eintrag)'', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Welche Prüfart?|Welche Prüfart?]]
|-
| DNS-Anbieter || Nur dns-01: ''acme-dns'', ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| Adresse (acme-dns) || Nur acme-dns: Adresse der Instanz, beginnt mit <code>https://</code>
|-
| Benutzer (acme-dns) || Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an
|-
| Schlüssel / API-Token || acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form <code>Präfix.Secret</code>
|-
| Name des TXT-Eintrags || Leer = <code>_acme-challenge.<Zertifikatsname></code>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die ''fulldomain'' des Kontos
|}

{{Hinweis|Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.}}

==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Dasselbe gilt hinter einem Reverse-Proxy: Alle Anfragen kommen dort von der IP-Adresse
des Proxys, und alle Konsumenten ohne API-Key teilen sich einen Zähler. Der Header
''X-Forwarded-For'' ändert daran nichts, er wird nur protokolliert.

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Immer geprüft wird:

* Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
* Nr und Name sind eindeutig.
* Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
* Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.

Nur bei '''aktivem''' Profil zusätzlich:

* Ohne ''kein SSL'' und ohne automatische Erneuerung sind Zertifikat und Schlüssel vorhanden.
* Bei ''mTLS-Modus aktiv'' ist das Root-Zertifikat vorhanden.
* Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und ''kein SSL'' ist nicht gesetzt.

{{Hinweis|Ein '''nicht aktives''' Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.}}

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe

2026-10-26T10:21:57Z

MINERVA-Rademacker: Zertifikat in allen Varianten nötig, auch hinter Proxy und im VPN [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Übersicht}}
= Öffentliche Freigabe =

Apps auf mobilen Geräten und externe Systeme erreichen den REST-Server nur, wenn er aus dem Internet erreichbar ist. Diese Seite stellt die drei Wege dafür gegenüber und richtet sich an die IT-Administration, die über die Freigabe entscheidet.

{{Hinweis|Der REST-Dienst läuft auf dem OBS-Server oder auf einem [[#REST-Dienst auf einem eigenen Server|eigenen Server]]. Auf dem OBS-Server läuft häufig auch die Datenbank. Die Varianten unterscheiden sich vor allem darin, ob eine Verbindung aus dem Internet den Server des REST-Dienstes direkt erreicht. Ein Zertifikat ist in allen Varianten nötig, auch im VPN, weil die App nur per HTTPS verbindet.}}

== Varianten im Vergleich ==
{| class="wikitable"
! Merkmal !! Direkte Portfreigabe !! Reverse-Proxy !! VPN
|-
| Aus dem Internet erreichbar || Server des REST-Dienstes: Port des REST-Servers, bei Prüfart http-01 zusätzlich Port 80 || nur der Proxy (Port 443) || nur das VPN-Gateway
|-
| Aufwand für die Nutzer der App || keiner || keiner || VPN-Client einrichten und vor der Nutzung einschalten
|-
| Aufwand für die IT || Portweiterleitung am Router || Proxy betreiben, Zertifikat am Proxy || VPN-Zugang für jedes Gerät
|-
| Filtern und Protokollieren vor dem REST-Dienst || – || ✓ || nur auf Netzebene
|-
| Zertifikat || im REST-Server, Prüfart http-01 oder dns-01 || öffentlich am Proxy, dazu eines im REST-Server für die Strecke vom Proxy || im REST-Server, Prüfart dns-01
|-
| REST-Server sieht die IP-Adresse des Geräts || ✓ || nur im Protokoll (über ''X-Forwarded-For'') || ✓, sofern das VPN-Gateway die Adressen nicht umsetzt (NAT)
|}

== Schutz durch den REST-Server ==
Unabhängig von der Variante schützt sich der REST-Server selbst. Diese Mechanismen greifen in allen drei Varianten:
* '''Verschlüsselung:''' ausschliesslich TLS 1.2 mit Forward Secrecy und AEAD-Verfahren. Unverschlüsselte Anfragen an einen TLS-Port werden vor jeder Verarbeitung abgewiesen. Optional mTLS: jeder Client braucht ein gültiges Client-Zertifikat.
* '''Zugänge:''' Jede Anfrage braucht einen gültigen API-Key, wahlweise zusätzlich JWT. Jeder Zugang ist nur für die Endpunkte freigeschaltet, die er braucht, und lässt sich auf eine Absenderadresse beschränken. API-Keys lassen sich ohne Unterbrechung tauschen.
* '''Widerrufbare Sitzungen:''' Eine Abmeldung wirkt sofort. Ein Refresh-Token gilt genau einmal; wird ein verbrauchtes erneut vorgelegt, sperrt der Server die ganze Sitzung.
* '''Grenzen gegen Missbrauch:''' getrenntes Rate-Limit für erfolgreiche und fehlgeschlagene Anfragen, eine Obergrenze gleichzeitiger Anfragen und Verbindungen sowie Grössengrenzen für Anfragen und Uploads.
* '''Keine Informationen nach aussen:''' Fehlerantworten enthalten nie interne Details. Die stehen nur im Protokoll, mit einer Korrelations-ID je Anfrage. Kennwörter und Token werden dort maskiert.
* '''Kurze Öffnung für die Zertifikatsprüfung:''' Bei http-01 öffnet der Dienst Port 80 nur für die Dauer der Prüfung.

Diese Mechanismen schützen den REST-Dienst. Reverse-Proxy und VPN fügen eine Schicht davor hinzu: Sie halten den Server des REST-Dienstes aus dem Internet heraus, und mit ihm häufig auch den OBS-Server und die Datenbank. Das wirkt auch gegen Schwachstellen ausserhalb des REST-Servers und gegen Überlastung.
Der Router leitet den Port des REST-Servers aus dem Internet auf den Server des REST-Dienstes weiter. Für die Zertifikatserneuerung mit der Prüfart http-01 wird zusätzlich Port 80 weitergeleitet.

'''Vorteile'''
* Die einfachste Einrichtung, es wird keine weitere Komponente gebraucht.
* Die App funktioniert überall, ohne dass die Nutzer etwas tun müssen.
* Der REST-Server sieht die IP-Adresse jedes Geräts. Alle Schutzmechanismen des REST-Servers, auch Host-Beschränkung und Rate-Limit, arbeiten damit je Gerät.

'''Nachteile'''
* Der Server des REST-Dienstes ist direkt aus dem Internet erreichbar. Läuft der REST-Dienst auf dem OBS-Server, gilt das für den OBS-Server und häufig auch für die Datenbank. Die [[#Schutz durch den REST-Server|Schutzmechanismen des REST-Servers]] greifen, eine zusätzliche Schicht davor gibt es aber nicht.
* Mit der Prüfart http-01 ist zusätzlich Port 80 weitergeleitet. Mit der Prüfart dns-01 entfällt das.

== Reverse-Proxy ==
Ein Reverse-Proxy, zum Beispiel in einer DMZ oder als Funktion der Firewall, nimmt HTTPS auf Port 443 an. Er prüft die Anfrage und reicht sie über eine eigene, ebenfalls verschlüsselte Verbindung an den REST-Server weiter.

'''Vorteile'''
* Der Server des REST-Dienstes ist aus dem Internet nicht erreichbar, nur der Proxy.
* Am Proxy lassen sich Anfragen nach Ihren Vorgaben filtern, drosseln und protokollieren.
* Für die Nutzer der App ändert sich nichts.
* Das öffentliche Zertifikat liegt am Proxy. Für die Strecke vom Proxy genügt im REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes. Es muss vor Ablauf getauscht werden.

'''Nachteile'''
* Der Proxy muss betrieben und gepflegt werden.
* Der REST-Server sieht als Absender nur den Proxy. Die Host-Beschränkung eines Zugangs kann keine Geräte unterscheiden, und Anfragen ohne API-Key teilen sich einen Zähler des Rate-Limits. Die IP-Adresse des Geräts steht nur im Protokoll, wenn der Proxy den Header ''X-Forwarded-For'' setzt.

Die Einrichtung beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].

== VPN ==
Die Geräte verbinden sich per VPN mit dem Netz, in dem der REST-Dienst läuft. Die App spricht durch den Tunnel per HTTPS mit dem REST-Server. Aus dem Internet ist nur das VPN-Gateway erreichbar.

'''Vorteile'''
* Für den REST-Server ist kein Port aus dem Internet offen.
* Nur Geräte mit VPN-Zugang erreichen den REST-Server.
* Setzt das VPN-Gateway die Adressen nicht um, sieht der REST-Server die VPN-Adresse jedes Geräts.

'''Nachteile'''
* Jedes Gerät braucht einen VPN-Client und einen eigenen Zugang. Ohne zentrale Geräteverwaltung schalten die Nutzer das VPN von Hand ein. Ist es aus, meldet die App, dass der Server nicht erreichbar ist.
* Ein VPN-Zugang öffnet den Weg ins Netz. Beschränken Sie ihn auf die Adresse und den Port des REST-Servers.
* Das Zertifikat lässt sich nur mit der Prüfart dns-01 erneuern, weil die Zertifizierungsstelle den Server nicht erreicht.
* Der Name des REST-Servers muss auf dem Gerät auf die interne Adresse zeigen. Das geht über einen DNS-Server, den das VPN mitliefert, oder über einen öffentlichen DNS-Eintrag mit der internen Adresse. Manche Router verwerfen solche Antworten als Schutz gegen DNS-Rebinding; dann löst der Name in diesem Netz nicht auf.

Das Zertifikat richten Sie wie unter [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] beschrieben mit der Prüfart dns-01 ein.

== REST-Dienst auf einem eigenen Server ==
Der REST-Dienst muss nicht auf dem OBS-Server laufen. Er lässt sich auch auf einem eigenen Server betreiben, zum Beispiel in einer DMZ. Voraussetzung ist, dass dieser Server
* per SMB auf den OBS-Server zugreifen kann und
* die Datenbank erreicht.

Der eigene Server lässt sich mit jeder der drei Varianten kombinieren. Bei der direkten Portfreigabe zeigt die Weiterleitung dann auf diesen Server statt auf den OBS-Server.

'''Vorteile'''
* Eine Verbindung aus dem Internet erreicht weder den OBS-Server noch die Datenbank direkt, auch bei direkter Portfreigabe.
* Die Verarbeitung der Anfragen läuft nicht auf dem OBS-Server. Die Datenbank wird weiterhin belastet.

'''Nachteile'''
* Ein weiterer Server muss betrieben und gepflegt werden.
* Vom eigenen Server ins interne Netz müssen SMB und der Port der Datenbank offen sein. Beschränken Sie diese Wege auf den OBS-Server und den Datenbankserver.

== Entscheidungshilfe ==
* '''Keine eingehende Verbindung zum OBS-Server erlaubt, DMZ oder Firewall mit Proxy-Funktion vorhanden:''' Reverse-Proxy.
* '''Keine eingehende Verbindung zum OBS-Server erlaubt, aber kein Proxy vorhanden:''' REST-Dienst auf einem eigenen Server in einer DMZ, mit direkter Portfreigabe auf diesen Server.
* '''Geräte werden zentral verwaltet oder ein VPN ist ohnehin im Einsatz:''' VPN.
* '''Kleine Installation ohne Vorgaben der IT:''' Direkte Portfreigabe, möglichst mit der Prüfart dns-01, damit Port 80 geschlossen bleibt.

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]]

OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung

2026-10-26T10:12:38Z

MINERVA-Rademacker: http-01: Server des REST-Dienstes statt OBS-Server [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Zertifikatserneuerung =

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

{{Auf einen Blick|1=
* '''Zwei Prüfarten.''' http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
* '''Selbsttest vorab.''' Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
* '''Erneuerung ab 30 Tagen Restlaufzeit.''' Das bisherige Zertifikat bleibt als Rückfall erhalten.
* '''dns-01 braucht nur ausgehende Verbindungen''' und eignet sich damit für VPN und für Server ohne Portfreigabe.
}}

== Voraussetzungen ==
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.firma.de''. Platzhalter-Zertifikate (''*.firma.de'') werden nicht unterstützt.
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL'''.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>).
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

=== Welche Prüfart? ===
{| class="wikitable"
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss
|-
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist || Port 80
|-
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts
|}

Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|öffentlichen Freigabe]] passt:
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy, die Erneuerung im REST-Server wird nicht gebraucht.
* '''VPN:''' dns-01.

=== Wege bei dns-01 ===
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag <code>_acme-challenge.<Name></code> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

{| class="wikitable"
! Weg !! Wann !! Einmalig beim DNS des Namens !! Einstellung '''DNS-Anbieter'''
|-
| Direkt beim Anbieter || Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS || nichts, Sie brauchen nur ein API-Token || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf eine Zone bei einem Anbieter || Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen || CNAME <code>_acme-challenge.<Name></code> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf acme-dns || Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister || CNAME <code>_acme-challenge.<Name></code> auf die ''fulldomain'' des acme-dns-Kontos || ''acme-dns''
|}

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

{{Hinweis|Namen von DynDNS-Diensten (zum Beispiel ''…myfritz.net'') eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.}}

== Vorgehen ==
=== Gemeinsame Einstellungen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server → Server''' und öffnen Sie das Server-Profil.
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''.
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll.
# Tragen Sie unter '''Kontakt bei der CA''' eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
# Richten Sie die Registerkarte '''5 DNS-Prüfung''' nach einem der folgenden Abschnitte ein und speichern Sie.
# Starten Sie den REST-Dienst neu.
}}

=== Prüfart http-01 ===
{{Schritte|1=
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
# Leiten Sie am Router Port 80 von aussen auf den Server des REST-Dienstes weiter.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer.
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein.
}}

Port 80 darf auf dem Server des REST-Dienstes von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

=== Prüfart dns-01 direkt beim DNS-Anbieter ===
{{Schritte|1=
# Erstellen Sie beim Anbieter der Zone ein API-Token:
#* '''Hetzner:''' ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
#* '''Cloudflare:''' ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
#* '''IONOS:''' einen API-Schlüssel. Er besteht aus Präfix und Secret.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''dns-01 (DNS-Eintrag)'' und im Feld '''DNS-Anbieter''' den Anbieter.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein, bei IONOS in der Form <code>Präfix.Secret</code>.
# Lassen Sie '''Name des TXT-Eintrags''' leer.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter ===
{{Schritte|1=
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs-firma.acme.example.de''. Einen Eintrag müssen Sie dort nicht anlegen.
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.firma.de</code> auf ''obs-firma.acme.example.de''.
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein.
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs-firma.acme.example.de''.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf acme-dns ===
{{Schritte|1=
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den DNS-Anbieter ''acme-dns''.
# Tragen Sie unter '''Adresse (acme-dns)''' die Adresse der Instanz ein. Sie beginnt mit <code>https://</code>.
# Lassen Sie '''Benutzer (acme-dns)''', '''Schlüssel / API-Token''' und '''Name des TXT-Eintrags''' leer und speichern Sie.
# Geben Sie in der Konsole <code>cert test</code> ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter '''Letzte Meldung''' steht danach der CNAME, den Sie anlegen müssen.
# Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: <code>_acme-challenge.<Name></code> auf die genannte ''fulldomain''.
# Geben Sie in der Konsole erneut <code>cert test</code> ein.
}}

{{Achtung|Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen ''fulldomain'' anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.}}

=== Erstes Zertifikat holen ===
Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

=== Testbetrieb ===
{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

== Ergebnis ==
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Unter '''Letzte Meldung''' steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt '''Zertifikat gültig bis''' das Ablaufdatum, und <code>cert</code> in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht.
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld '''Gesperrt bis''' zeigt, bis wann. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre.

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

== Wenn es nicht klappt ==
Die Meldungen stehen unter '''Letzte Meldung''' und im Protokoll des REST-Servers.

{| class="wikitable"
! Meldung !! Ursache
|-
| "Port 80 laesst sich nicht oeffnen - er ist belegt" || Ein anderer Dienst auf dem Server des REST-Dienstes belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
|-
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt
|-
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer
|-
| "acme-dns: Konto unvollstaendig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
|-
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
|-
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben
|-
| "IONOS: keine Zone zu … im Vertrag des Schluessels" || Der API-Schlüssel gehört zu einem anderen Vertrag
|-
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern
|-
| "… ist nach 210 Sekunden noch nicht ueberall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus
|-
| "kein oeffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
|-
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein
|}

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Automatische Zertifikatserneuerung|Server-Profile: Felder der Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-10-26T10:12:38Z

MINERVA-Rademacker: Reverse-Proxy: Server des REST-Dienstes statt OBS-Server [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|automatische Zertifikatserneuerung]]. Wie der Server von aussen erreichbar wird und welche Variante sich eignet, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Betrieb hinter einem Reverse-Proxy==

Soll der Server des REST-Dienstes nicht direkt aus dem Internet erreichbar sein, nimmt ein Reverse-Proxy die Anfragen entgegen, zum Beispiel in einer DMZ oder als Funktion der Firewall, und reicht sie an den REST-Dienst weiter. Von aussen ist nur der Proxy erreichbar. Vor- und Nachteile gegenüber Portfreigabe und VPN beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

Am Proxy und im Netz richten Sie ein:

* '''Öffentlicher Name:''' zeigt auf die öffentliche IP-Adresse des Proxys.
* '''Zertifikat:''' Der Proxy braucht ein öffentlich gültiges Zertifikat für diesen Namen. Die automatische Zertifikatserneuerung des REST-Servers wird nicht benötigt.
* '''Weiterleitung:''' Der Proxy leitet per HTTPS an <code>https://<Server des REST-Dienstes>:<Port></code> weiter. Für diese Strecke genügt am REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut.
* '''Header:''' Alle HTTP-Methoden und Header unverändert durchreichen, insbesondere ''Authorization'', ''apikey'' und ''Idempotency-Key''. Antworten nicht zwischenspeichern. Den Header ''X-Forwarded-For'' mit der IP-Adresse des Konsumenten setzen.
* '''Anfragegrösse:''' Die maximale Anfragegrösse am Proxy darf nicht unter der Upload-Grenze der Endpunkte liegen.
* '''Firewall:''' Den Port des REST-Servers intern nur für den Proxy freigeben.

Hinter dem Proxy verhält sich der REST-Server so:

* Protokoll und Konsole zeigen als Host die IP-Adresse des Proxys und hängen den Wert von ''X-Forwarded-For'' als <code>[xff=…]</code> an.
* Die [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]] eines Zugangs kann keine einzelnen Konsumenten unterscheiden.
* Beim [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Rate-Limit je Profil|Rate-Limit]] teilen sich alle Konsumenten ohne API-Key einen Zähler.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe

2026-10-26T10:12:38Z

MINERVA-Rademacker: Datenbank nicht zwingend auf dem Server des REST-Dienstes, Abschnitt REST-Dienst auf einem eigenen Server ergänzt [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Übersicht}}
= Öffentliche Freigabe =

Apps auf mobilen Geräten und externe Systeme erreichen den REST-Server nur, wenn er aus dem Internet erreichbar ist. Diese Seite stellt die drei Wege dafür gegenüber und richtet sich an die IT-Administration, die über die Freigabe entscheidet.

{{Hinweis|Der REST-Dienst läuft auf dem OBS-Server oder auf einem [[#REST-Dienst auf einem eigenen Server|eigenen Server]]. Auf dem OBS-Server läuft häufig auch die Datenbank. Die Varianten unterscheiden sich vor allem darin, ob eine Verbindung aus dem Internet den Server des REST-Dienstes direkt erreicht.}}

== Varianten im Vergleich ==
{| class="wikitable"
! Merkmal !! Direkte Portfreigabe !! Reverse-Proxy !! VPN
|-
| Aus dem Internet erreichbar || Server des REST-Dienstes: Port des REST-Servers, bei Prüfart http-01 zusätzlich Port 80 || nur der Proxy (Port 443) || nur das VPN-Gateway
|-
| Aufwand für die Nutzer der App || keiner || keiner || VPN-Client einrichten und vor der Nutzung einschalten
|-
| Aufwand für die IT || Portweiterleitung am Router || Proxy betreiben, Zertifikat am Proxy || VPN-Zugang für jedes Gerät
|-
| Filtern und Protokollieren vor dem REST-Dienst || – || ✓ || nur auf Netzebene
|-
| Öffentliches Zertifikat || im REST-Server, Prüfart http-01 oder dns-01 || am Proxy || im REST-Server, Prüfart dns-01
|-
| REST-Server sieht die IP-Adresse des Geräts || ✓ || nur im Protokoll (über ''X-Forwarded-For'') || ✓, sofern das VPN-Gateway die Adressen nicht umsetzt (NAT)
|}

== Schutz durch den REST-Server ==
Unabhängig von der Variante schützt sich der REST-Server selbst. Diese Mechanismen greifen in allen drei Varianten:
* '''Verschlüsselung:''' ausschliesslich TLS 1.2 mit Forward Secrecy und AEAD-Verfahren. Unverschlüsselte Anfragen an einen TLS-Port werden vor jeder Verarbeitung abgewiesen. Optional mTLS: jeder Client braucht ein gültiges Client-Zertifikat.
* '''Zugänge:''' Jede Anfrage braucht einen gültigen API-Key, wahlweise zusätzlich JWT. Jeder Zugang ist nur für die Endpunkte freigeschaltet, die er braucht, und lässt sich auf eine Absenderadresse beschränken. API-Keys lassen sich ohne Unterbrechung tauschen.
* '''Widerrufbare Sitzungen:''' Eine Abmeldung wirkt sofort. Ein Refresh-Token gilt genau einmal; wird ein verbrauchtes erneut vorgelegt, sperrt der Server die ganze Sitzung.
* '''Grenzen gegen Missbrauch:''' getrenntes Rate-Limit für erfolgreiche und fehlgeschlagene Anfragen, eine Obergrenze gleichzeitiger Anfragen und Verbindungen sowie Grössengrenzen für Anfragen und Uploads.
* '''Keine Informationen nach aussen:''' Fehlerantworten enthalten nie interne Details. Die stehen nur im Protokoll, mit einer Korrelations-ID je Anfrage. Kennwörter und Token werden dort maskiert.
* '''Kurze Öffnung für die Zertifikatsprüfung:''' Bei http-01 öffnet der Dienst Port 80 nur für die Dauer der Prüfung.

Diese Mechanismen schützen den REST-Dienst. Reverse-Proxy und VPN fügen eine Schicht davor hinzu: Sie halten den Server des REST-Dienstes aus dem Internet heraus, und mit ihm häufig auch den OBS-Server und die Datenbank. Das wirkt auch gegen Schwachstellen ausserhalb des REST-Servers und gegen Überlastung.
Der Router leitet den Port des REST-Servers aus dem Internet auf den Server des REST-Dienstes weiter. Für die Zertifikatserneuerung mit der Prüfart http-01 wird zusätzlich Port 80 weitergeleitet.

'''Vorteile'''
* Die einfachste Einrichtung, es wird keine weitere Komponente gebraucht.
* Die App funktioniert überall, ohne dass die Nutzer etwas tun müssen.
* Der REST-Server sieht die IP-Adresse jedes Geräts. Alle Schutzmechanismen des REST-Servers, auch Host-Beschränkung und Rate-Limit, arbeiten damit je Gerät.

'''Nachteile'''
* Der Server des REST-Dienstes ist direkt aus dem Internet erreichbar. Läuft der REST-Dienst auf dem OBS-Server, gilt das für den OBS-Server und häufig auch für die Datenbank. Die [[#Schutz durch den REST-Server|Schutzmechanismen des REST-Servers]] greifen, eine zusätzliche Schicht davor gibt es aber nicht.
* Mit der Prüfart http-01 ist zusätzlich Port 80 weitergeleitet. Mit der Prüfart dns-01 entfällt das.

== Reverse-Proxy ==
Ein Reverse-Proxy, zum Beispiel in einer DMZ oder als Funktion der Firewall, nimmt HTTPS auf Port 443 an. Er prüft die Anfrage und reicht sie über eine eigene, ebenfalls verschlüsselte Verbindung an den REST-Server weiter.

'''Vorteile'''
* Der Server des REST-Dienstes ist aus dem Internet nicht erreichbar, nur der Proxy.
* Am Proxy lassen sich Anfragen nach Ihren Vorgaben filtern, drosseln und protokollieren.
* Für die Nutzer der App ändert sich nichts.
* Das öffentliche Zertifikat liegt am Proxy. Die Zertifikatserneuerung des REST-Servers wird nicht gebraucht.

'''Nachteile'''
* Der Proxy muss betrieben und gepflegt werden.
* Der REST-Server sieht als Absender nur den Proxy. Die Host-Beschränkung eines Zugangs kann keine Geräte unterscheiden, und Anfragen ohne API-Key teilen sich einen Zähler des Rate-Limits. Die IP-Adresse des Geräts steht nur im Protokoll, wenn der Proxy den Header ''X-Forwarded-For'' setzt.

Die Einrichtung beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].

== VPN ==
Die Geräte verbinden sich per VPN mit dem Netz, in dem der REST-Dienst läuft. Die App spricht durch den Tunnel per HTTPS mit dem REST-Server. Aus dem Internet ist nur das VPN-Gateway erreichbar.

'''Vorteile'''
* Für den REST-Server ist kein Port aus dem Internet offen.
* Nur Geräte mit VPN-Zugang erreichen den REST-Server.
* Setzt das VPN-Gateway die Adressen nicht um, sieht der REST-Server die VPN-Adresse jedes Geräts.

'''Nachteile'''
* Jedes Gerät braucht einen VPN-Client und einen eigenen Zugang. Ohne zentrale Geräteverwaltung schalten die Nutzer das VPN von Hand ein. Ist es aus, meldet die App, dass der Server nicht erreichbar ist.
* Ein VPN-Zugang öffnet den Weg ins Netz. Beschränken Sie ihn auf die Adresse und den Port des REST-Servers.
* Das Zertifikat lässt sich nur mit der Prüfart dns-01 erneuern, weil die Zertifizierungsstelle den Server nicht erreicht.
* Der Name des REST-Servers muss auf dem Gerät auf die interne Adresse zeigen. Das geht über einen DNS-Server, den das VPN mitliefert, oder über einen öffentlichen DNS-Eintrag mit der internen Adresse. Manche Router verwerfen solche Antworten als Schutz gegen DNS-Rebinding; dann löst der Name in diesem Netz nicht auf.

Das Zertifikat richten Sie wie unter [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] beschrieben mit der Prüfart dns-01 ein.

== REST-Dienst auf einem eigenen Server ==
Der REST-Dienst muss nicht auf dem OBS-Server laufen. Er lässt sich auch auf einem eigenen Server betreiben, zum Beispiel in einer DMZ. Voraussetzung ist, dass dieser Server
* per SMB auf den OBS-Server zugreifen kann und
* die Datenbank erreicht.

Der eigene Server lässt sich mit jeder der drei Varianten kombinieren. Bei der direkten Portfreigabe zeigt die Weiterleitung dann auf diesen Server statt auf den OBS-Server.

'''Vorteile'''
* Eine Verbindung aus dem Internet erreicht weder den OBS-Server noch die Datenbank direkt, auch bei direkter Portfreigabe.
* Die Verarbeitung der Anfragen läuft nicht auf dem OBS-Server. Die Datenbank wird weiterhin belastet.

'''Nachteile'''
* Ein weiterer Server muss betrieben und gepflegt werden.
* Vom eigenen Server ins interne Netz müssen SMB und der Port der Datenbank offen sein. Beschränken Sie diese Wege auf den OBS-Server und den Datenbankserver.

== Entscheidungshilfe ==* '''Keine eingehende Verbindung zum OBS-Server erlaubt, DMZ oder Firewall mit Proxy-Funktion vorhanden:''' Reverse-Proxy.
* '''Keine eingehende Verbindung zum OBS-Server erlaubt, aber kein Proxy vorhanden:''' REST-Dienst auf einem eigenen Server in einer DMZ, mit direkter Portfreigabe auf diesen Server.
* '''Geräte werden zentral verwaltet oder ein VPN ist ohnehin im Einsatz:''' VPN.
* '''Kleine Installation ohne Vorgaben der IT:''' Direkte Portfreigabe, möglichst mit der Prüfart dns-01, damit Port 80 geschlossen bleibt.

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]]

OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung

2026-10-26T09:47:31Z

MINERVA-Rademacker: Beispiel-Domain firma.de statt kunde.de [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Zertifikatserneuerung =

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

{{Auf einen Blick|1=
* '''Zwei Prüfarten.''' http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
* '''Selbsttest vorab.''' Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
* '''Erneuerung ab 30 Tagen Restlaufzeit.''' Das bisherige Zertifikat bleibt als Rückfall erhalten.
* '''dns-01 braucht nur ausgehende Verbindungen''' und eignet sich damit für VPN und für Server ohne Portfreigabe.
}}

== Voraussetzungen ==
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.firma.de''. Platzhalter-Zertifikate (''*.firma.de'') werden nicht unterstützt.
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL'''.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>).
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

=== Welche Prüfart? ===
{| class="wikitable"
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss
|-
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist || Port 80
|-
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts
|}

Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|öffentlichen Freigabe]] passt:
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy, die Erneuerung im REST-Server wird nicht gebraucht.
* '''VPN:''' dns-01.

=== Wege bei dns-01 ===
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag <code>_acme-challenge.<Name></code> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

{| class="wikitable"
! Weg !! Wann !! Einmalig beim DNS des Namens !! Einstellung '''DNS-Anbieter'''
|-
| Direkt beim Anbieter || Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS || nichts, Sie brauchen nur ein API-Token || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf eine Zone bei einem Anbieter || Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen || CNAME <code>_acme-challenge.<Name></code> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf acme-dns || Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister || CNAME <code>_acme-challenge.<Name></code> auf die ''fulldomain'' des acme-dns-Kontos || ''acme-dns''
|}

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

{{Hinweis|Namen von DynDNS-Diensten (zum Beispiel ''…myfritz.net'') eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.}}

== Vorgehen ==
=== Gemeinsame Einstellungen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server → Server''' und öffnen Sie das Server-Profil.
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''.
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll.
# Tragen Sie unter '''Kontakt bei der CA''' eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
# Richten Sie die Registerkarte '''5 DNS-Prüfung''' nach einem der folgenden Abschnitte ein und speichern Sie.
# Starten Sie den REST-Dienst neu.
}}

=== Prüfart http-01 ===
{{Schritte|1=
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
# Leiten Sie am Router Port 80 von aussen auf den OBS-Server weiter.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer.
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein.
}}

Port 80 darf auf dem OBS-Server von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

=== Prüfart dns-01 direkt beim DNS-Anbieter ===
{{Schritte|1=
# Erstellen Sie beim Anbieter der Zone ein API-Token:
#* '''Hetzner:''' ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
#* '''Cloudflare:''' ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
#* '''IONOS:''' einen API-Schlüssel. Er besteht aus Präfix und Secret.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''dns-01 (DNS-Eintrag)'' und im Feld '''DNS-Anbieter''' den Anbieter.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein, bei IONOS in der Form <code>Präfix.Secret</code>.
# Lassen Sie '''Name des TXT-Eintrags''' leer.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter ===
{{Schritte|1=
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs-firma.acme.example.de''. Einen Eintrag müssen Sie dort nicht anlegen.
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.firma.de</code> auf ''obs-firma.acme.example.de''.
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein.
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs-firma.acme.example.de''.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf acme-dns ===
{{Schritte|1=
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den DNS-Anbieter ''acme-dns''.
# Tragen Sie unter '''Adresse (acme-dns)''' die Adresse der Instanz ein. Sie beginnt mit <code>https://</code>.
# Lassen Sie '''Benutzer (acme-dns)''', '''Schlüssel / API-Token''' und '''Name des TXT-Eintrags''' leer und speichern Sie.
# Geben Sie in der Konsole <code>cert test</code> ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter '''Letzte Meldung''' steht danach der CNAME, den Sie anlegen müssen.
# Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: <code>_acme-challenge.<Name></code> auf die genannte ''fulldomain''.
# Geben Sie in der Konsole erneut <code>cert test</code> ein.
}}

{{Achtung|Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen ''fulldomain'' anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.}}

=== Erstes Zertifikat holen ===
Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

=== Testbetrieb ===
{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

== Ergebnis ==
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Unter '''Letzte Meldung''' steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt '''Zertifikat gültig bis''' das Ablaufdatum, und <code>cert</code> in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht.
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld '''Gesperrt bis''' zeigt, bis wann. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre.

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

== Wenn es nicht klappt ==
Die Meldungen stehen unter '''Letzte Meldung''' und im Protokoll des REST-Servers.

{| class="wikitable"
! Meldung !! Ursache
|-
| "Port 80 laesst sich nicht oeffnen - er ist belegt" || Ein anderer Dienst auf dem OBS-Server belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
|-
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt
|-
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer
|-
| "acme-dns: Konto unvollstaendig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
|-
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
|-
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben
|-
| "IONOS: keine Zone zu … im Vertrag des Schluessels" || Der API-Schlüssel gehört zu einem anderen Vertrag
|-
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern
|-
| "… ist nach 210 Sekunden noch nicht ueberall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus
|-
| "kein oeffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
|-
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein
|}

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Automatische Zertifikatserneuerung|Server-Profile: Felder der Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-10-26T09:47:30Z

MINERVA-Rademacker: Beispiel-Domains und mTLS-Beispiele: firma.de statt kunde.de [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Ein Wildcard-Zugang eignet
sich deshalb für Artefakte, die für jeden bestimmt sind (Test-APK, Handbuch),
'''nicht''' für Kundenbelege. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].}}

{{Hinweis|Bei einem Wildcard-Zugang sollte ''CORS-Origin'' '''leer''' bleiben.
Ein ''*'' dort wirkt auf die Preflight-Antwort '''aller''' Zugänge (siehe unten);
ein Download über die Adresszeile des Browsers sendet ohnehin kein ''Origin'',
CORS greift dort also gar nicht.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

{{Hinweis|Hinter einem Reverse-Proxy ist die Remote-IP immer die des Proxys. Die Host-Beschränkung kann dort keine einzelnen Konsumenten unterscheiden. Der Header ''X-Forwarded-For'' wird dafür bewusst nicht ausgewertet, weil jeder Client ihn selbst setzen kann.}}

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.firma.de;https://test.firma.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

{{Achtung|Die Lebensdauer eines Refresh-Tokens ist nach oben auf '''372 Tage'''
begrenzt. Ein mit ''_OBS_JWT_REFRESH_EXP'' länger ausgestelltes Token wird bei der
Vorlage '''nicht mehr verifiziert''' und mit 401 abgewiesen - der Fehler fällt
also erst Monate später auf, beim ersten Erneuerungsversuch.}}

Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''', dem Code ''AUTH_FAILED'' und reicht den Text aus dem Feld
''error'' als ''error.message'' an den Client durch - der Konsument kann ihn also
direkt anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|''AUTH_FAILED'' unterscheidet die '''abgelehnte Anmeldung''' vom
''AUTH_EXPIRED'', das ein abgelaufenes oder gesperrtes Token liefert. Ein Client
sollte auf den Code reagieren und nicht auf den Text: Bei ''AUTH_FAILED'' gehört
die Anmeldemaske noch einmal vorgelegt, bei ''AUTH_EXPIRED'' erst ein Refresh
versucht.}}

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('all');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Woher ein Anmelder seine Identität bekommt==

'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.

Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.

Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt". Schickt ein Reverse-Proxy den Header
''X-Forwarded-For'' mit, steht dessen Wert zusätzlich in ''rt_ip_fwd''; ''rt_ip'' bleibt
die IP-Adresse der Verbindung.

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Firma GmbH/CN=client-prod.firma.de
/C=DE/O=Firma GmbH/CN=client-test.firma.de

Mit '''CN=client-prod.firma.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Firma GmbH;CN=client-prod.firma.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Beispiel3

2026-10-26T09:47:30Z

MINERVA-Rademacker: Umlaute ausgeschrieben, Beispiel-Domain firma.de statt kunde.de [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Beispiel 3: Datensatz anlegen mit JSON-Body=

Dieses Beispiel zeigt einen Endpunkt mit allen vier CRUD-Zugriffen (GET, POST, PUT und - anstelle von DELETE - PATCH, siehe den Hinweis beim Schliessen). Es geht um Tickets eines externen Servicedesks, der Tickets über den OBS REST-Server in OBS einliefern, abrufen, aktualisieren und schliessen kann.

{{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über einen Query-Parameter (''?id...''). Alternativ lässt sich dieselbe Ressource über ein Pfad-Template wie ''/tickets/{id}'' ansprechen; die ID steht dann als ''oReader.Path('id')'' bereit. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].}}

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'', Bindung 0.0.0.0:443
* '''Zugang:''' ''Servicedesk-X''
** API-Key: zufällig generiert
** Host: ''servicedesk.firma.de'' (DNS-gebunden, IP-Zugriff wird abgelehnt)
** JWT: nicht aktiv
* '''Endpunkt:''' ''tickets/v1'', Profil ''Public-API''
* '''Berechtigung:''' Zugang ''Servicedesk-X'' für Endpunkt ''tickets/v1'' freigeschaltet

==Endpunkt-Skript ''tickets/v1''==

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Hilfsprozedur: die FELDER eines Tickets. Sie bekommt den Writer und schreibt
// in das Objekt, das der Aufrufer geoeffnet hat - einmal als Listeneintrag,
// einmal in die Wurzel. Ein Helfer, der ein Fragment als String zurueckgibt,
// waere der alte Weg; dabei ging die Reihenfolge im Zusammenbau verloren.
//------------------------------------------------------------------------------

procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
const cOffset: string);
begin
oWriter.Str ('id' , qTicket.A2UID());
oWriter.Str ('nr' , qTicket.A2C('ti_nr'));
oWriter.Str ('betreff', qTicket.A2C('ti_betreff'));
oWriter.Str ('status' , qTicket.A2C('ti_status'));
oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
// Zeitpunkte gehen als ISO-8601 MIT OFFSET ueber die Leitung, nicht im
// SQL-Format: DTToSQL liefert 'JJJJ-MM-TT hh:mm:ss' ohne Zeitzone, und der
// Konsument muss dann raten, in welcher er steht. RestIsoFromDate nimmt den
// Offset des Servers dazu. Ein leeres Datum ergibt null, nicht 1899.
oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;

// Fuer den Body-Zugriff und fuer Fehlerantworten braucht es keine eigenen
// Hilfsfunktionen mehr: oReader liest typisiert, oWriter.Error baut die
// vollstaendige Fehlerhuelle samt traceId.

//------------------------------------------------------------------------------
// GET /tickets/v1?id=... - einzelnes Ticket
// GET /tickets/v1 - alle offenen Tickets
//------------------------------------------------------------------------------

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
qData : TxFQuery;
cId : string;
cOffset : string;
lGefunden: Boolean;
begin
cId := oReader.Param('id');
// Der Offset des Servers geht in jeden Zeitstempel der Antwort.
cOffset := oReader.Offset();

if (not Empty(cId)) then begin
lGefunden := false;
cSql := 'SELECT * FROM tickets WHERE sys_uid = ' + DB_SQLVal(cId);
if (DB_SOpen(oDB, cSql, qData)) then begin
// EoF gehoert dazu: DB_SOpen sagt nur, dass die ABFRAGE lief.
if (not qData.EoF) then begin
_TicketFelder(oWriter, qData, cOffset);
lGefunden := true;
end;
end;
DB_Close(qData);

if (not lGefunden) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
end;
end else begin
// Die Liste ist eine nackte Liste. RootArr steht vor der Abfrage:
// kein Treffer heisst leere Liste, nicht leeres Objekt.
oWriter.RootArr();
cSql := 'SELECT * FROM tickets WHERE ti_status <> "9" ORDER BY ti_aend_dat DESC';
if (DB_SOpen(oDB, cSql, qData)) then begin
while (not qData.EoF) do begin
oWriter.ObjBegin('');
_TicketFelder(oWriter, qData, cOffset);
oWriter.ObjEnd;
qData.Next();
end;
end;
DB_Close(qData);
end;
end;

//------------------------------------------------------------------------------
// POST /tickets/v1 - neues Ticket anlegen
// Body: { "betreff":"...", "beschr":"..." }
//------------------------------------------------------------------------------

procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket : TqSQL;
cId : string;
cBetreff: string;
cBeschr : string;
lOk : Boolean;
begin
// HasBody unterscheidet "kein Koerper" von "Koerper ohne das Feld" - das
// erste ist ein 400, das zweite ein 422.
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cBetreff := '';
cBeschr := '';
oReader.Str('betreff', cBetreff);
oReader.Str('beschr' , cBeschr);

if (Empty(cBetreff)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
exit;
end;

cId := GetNewId(oDB);

xTicket := qSqlInit(oDB, 'tickets');
xTicket.lNoSysUID := True;
try
xTicket.qSet('sys_uid' , cId);
xTicket.qSet('ti_nr' , DB_NeuNum(oDB, 'tickets', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
xTicket.qSet('ti_betreff' , cBetreff);
xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_status' , '1');
xTicket.qSet('ti_anl_dat' , Now());
xTicket.qSet('ti_aend_dat', Now());
// SaveData liefert einen Boolean. Ein SQL-Fehler - etwa Duplicate entry
// auf einem eindeutigen Index - wirft KEINE Exception und steht in
// keinem Protokoll. Ohne diese Auswertung antwortet der Endpunkt mit
// 201, ohne etwas angelegt zu haben.
lOk := xTicket.SaveData(NEW_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
exit;
end;

oWriter.Str('id' , cId);
oWriter.Str('status', 'created');
oWriter.Status(201);
oWriter.Header('Location', '/tickets/v1?id=' + cId);
end;

//------------------------------------------------------------------------------
// PUT /tickets/v1 - Ticket aktualisieren
// Body: { "id":"...", "status":"...", "beschr":"..." }
//------------------------------------------------------------------------------

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
lOk : Boolean;
cId : string;
cStat : string;
cBeschr: string;
begin
if (not oReader.HasBody()) then begin
oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
exit;
end;

cId := '';
cStat := '';
cBeschr := '';
oReader.Str('id' , cId);
oReader.Str('status', cStat);
oReader.Str('beschr', cBeschr);

if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

// Zum Aendern qSqlInit mit sys_uid, nicht qSqlRead: qSqlRead liest den
// Altsatz und schreibt nur Aenderungen - ein unveraenderter Wert erzeugt
// gar kein Write und SaveData liefert False.
xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
if (not Empty(cStat)) then xTicket.qSet('ti_status' , cStat);
if (not Empty(cBeschr)) then xTicket.qSet('ti_beschr' , cBeschr);
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geaendert werden');
exit;
end;

oWriter.Str('status', 'updated');
end;

//------------------------------------------------------------------------------
// PATCH /tickets/v1?id=... - Ticket schliessen (Soft-Delete via Status=9)
//
// NICHT als DELETE: 'Delete' ist in der Skriptsprache eine Standardprozedur,
// eine eigene Prozedur dieses Namens laesst sich nicht uebersetzen. Solange das
// so ist, laeuft ein Loeschen ueber PATCH oder POST. Siehe den Hinweis unten.
//------------------------------------------------------------------------------

procedure Patch(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
cId : string;
lOk : Boolean;
begin
cId := oReader.Param('id');
if (Empty(cId)) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
exit;
end;

if (not DB_LSeek(oDB, 'tickets', 'sys_uid = ' + DB_SQLVal(cId))) then begin
oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
exit;
end;

xTicket := qSqlInit(oDB, 'tickets');
xTicket.qSet('sys_uid', cId);
try
xTicket.qSet('ti_status' , '9');
xTicket.qSet('ti_aend_dat', Now());
lOk := xTicket.SaveData(UPDATE_RECORD);
finally
qSqlFree(xTicket);
end;

if (not lOk) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
exit;
end;

oWriter.Str('status', 'closed');
end;
</syntaxhighlight>

{{Achtung|'''Ein DELETE-Endpunkt kann derzeit kein Skript haben.''' Der Server
ruft die Prozedur, die genauso heisst wie das HTTP-Verb - für DELETE also
<code>Delete</code>. Dieser Name ist in der Skriptsprache belegt
(Standardprozedur zum Löschen aus einer Zeichenkette), und die Deklaration
lässt sich nicht übersetzen; die Meldung nennt dabei nur die Zeile, nicht die
Ursache. Bis das gelöst ist: das Löschen als <code>PATCH</code> oder
<code>POST</code> mit einer Aktion abbilden. Das Abmelden am JWT-Endpunkt ist
davon nicht betroffen - es läuft als DELETE '''ohne''' Skript vollständig in
der Engine.}}

==Aufruf mit curl==

Liste aller offenen Tickets:

curl -H "apikey: [API-KEY]" https://api.meinserver.de/tickets/v1

Einzelnes Ticket:

curl -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

Neues Ticket anlegen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"betreff\":\"Drucker offline\",\"beschr\":\"Etage 2, Raum 23\"}" ^
https://api.meinserver.de/tickets/v1

Ticket aktualisieren:

curl -X PUT -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"id\":\"abc-123\",\"status\":\"2\"}" ^
https://api.meinserver.de/tickets/v1

Ticket schliessen:

curl -X PATCH -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"

==Aufruf aus PHP==

<syntaxhighlight lang="php" line>
<?php
$apikey = '[API-KEY]';
$base = 'https://api.meinserver.de/tickets/v1';

function rest($method, $url, $apikey, $body = null) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL , $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
$headers = ['apikey: ' . $apikey];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}

// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
'betreff' => 'Drucker offline',
'beschr' => 'Etage 2, Raum 23'
]);
$id = $neu['id'];

// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2']);

// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
?>
</syntaxhighlight>

==Was zeigt das Beispiel?==

* Saubere Trennung der CRUD-Methoden in einem Endpunkt.
* Verwendung des JSON-Body für komplexere Eingangsdaten (POST, PUT).
* Verwendung von Query-Parametern für einfache Werte (GET, PATCH).
* Soft-Delete über Status-Änderung statt physischer Löschung - und warum er als PATCH und nicht als DELETE läuft.
* Eindeutige Audit-UIDs (''Y00CXXXXxx'') für jeden DB-Zugriff zur Nachvollziehbarkeit.
* Host-gebundener Zugang als zweite Sicherheitsebene neben dem API-Key.
* Alternativ: ID per Pfad-Parameter statt Query-Parameter (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4]]).

OBS/Kostenpflichtige Module/RESTServer/Beispiel1

2026-10-26T09:47:29Z

MINERVA-Rademacker: Umlaute ausgeschrieben, Beispiel-Domain firma.de statt kunde.de [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Beispiel 1: Daten-Abruf mit JWT-Authentifizierung=

In diesem Beispiel werden Steuerungs-Variablen aus OBS abgerufen und auf einer Webseite ausgegeben. Der Zugang ist mit JWT-Pflicht eingerichtet, der Konsument muss sich daher zuerst anmelden und einen Token bezogen haben.

==Einrichtung in OBS==

* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' mit Bindung 0.0.0.0:443
* '''Zugang:''' ''Web-Dashboard''
** API-Key: zufällig generiert
** JWT aktiv, JWT-Endpunkt ''oauth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
** CORS-Origins: ''https://dashboard.firma.de''
* '''Endpunkt:''' ''steuerung/v1'', dem Profil ''Public-API'' zugeordnet
* '''Berechtigung:''' Zugang ''Web-Dashboard'' für Endpunkt ''steuerung/v1'' freigeschaltet

==JWT-Authentifizierungs-Skript (Zugang)==

Wird über die Zugänge-Liste mit '''F7''' geöffnet. Prüfen, ob Benutzername/Passwort gegen die OBS-Benutzerverwaltung passen.

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser : string;
cPass : string;
cSql : string;
qUser : TxFQuery;
lOk : Boolean;
begin
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

cSql := 'SELECT u_nr, u_name FROM benutzer' +
' WHERE u_login = ' + DB_SQLVal(cUser) +
' AND u_passwort_hash = ' + DB_SQLVal(HashPasswort(cPass)) +
' AND u_aktiv = ' + DB_SQLVal('1');

// DB_SOpen liefert true, wenn die ABFRAGE lief - nicht, wenn ein
// Datensatz gefunden wurde. Ohne die EoF-Pruefung wuerde jede
// Anmeldung gelingen, sobald das SQL fehlerfrei ist.
lOk := false;
if (DB_SOpen(oDB, cSql, qUser)) then begin
if (not qUser.EoF) then begin
lOk := true;
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , qUser.A2C('u_nr'));
oWriter.Str('_OBS_JWT_SUBJECT' , qUser.A2C('u_name'));
oWriter.Str('_OBS_JWT_AUDIENCE', 'dashboard');
end;
end;
DB_Close(qUser);

if (not lOk) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Benutzer oder Passwort ist falsch');
end;
end;
</syntaxhighlight>

{{Hinweis|Hier steht in ''_OBS_JWT_ID'' die Benutzernummer - derselbe Wert also bei
jeder Anmeldung desselben Benutzers. Das ist zulässig: der Server führt seine
Sitzungen über eigene Kennungen (''sid''/''rid''), nicht über das ''jti'' des
Skripts. Mehrfache und parallele Anmeldungen eines Benutzers sind damit
unproblematisch.}}

==Endpunkt-Skript ''steuerung/v1''==

Liefert eine Liste von Steuerungs-Werten zurück. Die Auswertung der JWT-Claims sorgt dafür, dass nur Audience ''dashboard'' Daten erhält.

<syntaxhighlight lang="pascal" line>
//------------------------------------------------------------------------------
// Ein Wert als Listeneintrag. Der Helfer bekommt den WRITER und schreibt an
// der Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurueck.
// Der leere Feldname ist der Eintrag einer Liste.
//------------------------------------------------------------------------------

procedure _AddVar(oWriter: TxRestWriter; const cVar: string);
var cTitel : string;
cData : string;
cEinh : string;
lString: Boolean;
lAlign : Boolean;
begin
if (ST_Variable(oDB, cVar, cTitel, cData, cEinh, lString, lAlign)) then begin
oWriter.ObjBegin('');
oWriter.Str('variable', cVar);
oWriter.Str('titel' , cTitel);
oWriter.Str('wert' , cData);
oWriter.Str('einheit' , cEinh);
oWriter.ObjEnd;
end;
end;

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// Audience-Pruefung: nur Dashboard-Tokens akzeptieren. Die Ablehnung ist
// ein 403 und keine 200 mit Fehlertext - oWriter.Error baut dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
if (oReader.Param('_OBS_JWT_AUDIENCE') <> 'dashboard') then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Token nicht für diese Anwendung ausgestellt');
exit;
end;

// Die Antwort ist eine nackte Liste, kein Objekt: RootArr sagt das, und
// zwar VOR dem ersten Eintrag. Ein ArrEnd gibt es dazu nicht - die
// Wurzelklammer setzt der Server.
oWriter.RootArr();
_AddVar(oWriter, 'WERT_1');
_AddVar(oWriter, 'WERT_2');
_AddVar(oWriter, 'WERT_3');
_AddVar(oWriter, 'WERT_4');
end;
</syntaxhighlight>

==JavaScript-Client (Browser)==

Im Browser werden zwei Aufrufe gemacht: erst Token holen, dann Daten lesen.

<syntaxhighlight lang="javascript" line>
const API_BASE = 'https://api.meinserver.de';
const API_KEY = '[API-KEY]';

async function login(username, password) {
const res = await fetch(`${API_BASE}/oauth/`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'apikey': API_KEY },
body: JSON.stringify({ username, password })
});
if (!res.ok) throw new Error('Login fehlgeschlagen');
const data = await res.json();
return data.token;
}

async function ladeSteuerung(token) {
const res = await fetch(`${API_BASE}/steuerung/v1`, {
method: 'GET',
headers: {
'apikey': API_KEY,
'Authorization': 'Bearer ' + token
}
});
if (!res.ok) throw new Error('Abruf fehlgeschlagen: ' + res.status);
return res.json();
}

async function zeigeTabelle() {
const token = await login('mitarbeiter', 'geheim');
const werte = await ladeSteuerung(token);

const tbl = document.getElementById('steuerung');
werte.forEach(w => {
const tr = document.createElement('tr');
tr.innerHTML = `<td>${w.titel}</td><td>${w.wert} ${w.einheit}</td>`;
tbl.appendChild(tr);
});
}

zeigeTabelle();
</syntaxhighlight>

==Test mit curl==

Token holen:

curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
-d "{\"username\":\"mitarbeiter\",\"password\":\"geheim\"}" ^
https://api.meinserver.de/oauth/

Antwort:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 3600,
"serverTime": "2026-08-19T09:12:33+02:00"}

Da das Skript kein ''_OBS_JWT_REFRESH_ID'' liefert, enthält die Antwort kein
''refreshToken'' - der Client meldet sich nach Ablauf der 60 Minuten neu an.

Daten abrufen:

curl -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJhbGciOi..." ^
https://api.meinserver.de/steuerung/v1

==Was zeigt das Beispiel?==

* Zweistufige Anmeldung: API-Key + JWT.
* Sichere Trennung von Konsumenten-Gruppen über die Audience-Claim.
* Eigenes Authentifizierungs-Skript pro Zugang.
* Browser-Zugriff über CORS-erlaubtes Origin.
* Anmeldung ohne Refresh-Token: einfachster Fall, der Token läuft nach der Zeit aus ''JWT-Exp'' ab.

OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe

2026-10-26T09:41:07Z

MINERVA-Rademacker: Abschnitt Schutz durch den REST-Server ergänzt, Portfreigabe: Vor- und Nachteil präzisiert [Volltext ersetzt]

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Übersicht}}
= Öffentliche Freigabe =

Apps auf mobilen Geräten und externe Systeme erreichen den REST-Server nur, wenn er aus dem Internet erreichbar ist. Diese Seite stellt die drei Wege dafür gegenüber und richtet sich an die IT-Administration, die über die Freigabe entscheidet.

{{Hinweis|Läuft der REST-Server auf dem OBS-Server, liegt dort auch die Datenbank. Die Varianten unterscheiden sich vor allem darin, ob eine Verbindung aus dem Internet diesen Server direkt erreicht.}}

== Varianten im Vergleich ==
{| class="wikitable"
! Merkmal !! Direkte Portfreigabe !! Reverse-Proxy !! VPN
|-
| Aus dem Internet erreichbar || OBS-Server: Port des REST-Servers, bei Prüfart http-01 zusätzlich Port 80 || nur der Proxy (Port 443) || nur das VPN-Gateway
|-
| Aufwand für die Nutzer der App || keiner || keiner || VPN-Client einrichten und vor der Nutzung einschalten
|-
| Aufwand für die IT || Portweiterleitung am Router || Proxy betreiben, Zertifikat am Proxy || VPN-Zugang für jedes Gerät
|-
| Filtern und Protokollieren vor dem OBS-Server || – || ✓ || nur auf Netzebene
|-
| Öffentliches Zertifikat || im REST-Server, Prüfart http-01 oder dns-01 || am Proxy || im REST-Server, Prüfart dns-01
|-
| REST-Server sieht die IP-Adresse des Geräts || ✓ || nur im Protokoll (über ''X-Forwarded-For'') || ✓, sofern das VPN-Gateway die Adressen nicht umsetzt (NAT)
|}

== Schutz durch den REST-Server ==
Unabhängig von der Variante schützt sich der REST-Server selbst. Diese Mechanismen greifen in allen drei Varianten:
* '''Verschlüsselung:''' ausschliesslich TLS 1.2 mit Forward Secrecy und AEAD-Verfahren. Unverschlüsselte Anfragen an einen TLS-Port werden vor jeder Verarbeitung abgewiesen. Optional mTLS: jeder Client braucht ein gültiges Client-Zertifikat.
* '''Zugänge:''' Jede Anfrage braucht einen gültigen API-Key, wahlweise zusätzlich JWT. Jeder Zugang ist nur für die Endpunkte freigeschaltet, die er braucht, und lässt sich auf eine Absenderadresse beschränken. API-Keys lassen sich ohne Unterbrechung tauschen.
* '''Widerrufbare Sitzungen:''' Eine Abmeldung wirkt sofort. Ein Refresh-Token gilt genau einmal; wird ein verbrauchtes erneut vorgelegt, sperrt der Server die ganze Sitzung.
* '''Grenzen gegen Missbrauch:''' getrenntes Rate-Limit für erfolgreiche und fehlgeschlagene Anfragen, eine Obergrenze gleichzeitiger Anfragen und Verbindungen sowie Grössengrenzen für Anfragen und Uploads.
* '''Keine Informationen nach aussen:''' Fehlerantworten enthalten nie interne Details. Die stehen nur im Protokoll, mit einer Korrelations-ID je Anfrage. Kennwörter und Token werden dort maskiert.
* '''Kurze Öffnung für die Zertifikatsprüfung:''' Bei http-01 öffnet der Dienst Port 80 nur für die Dauer der Prüfung.

Diese Mechanismen schützen den REST-Dienst. Reverse-Proxy und VPN fügen eine Schicht davor hinzu: Sie halten den Server, auf dem auch die Datenbank läuft, aus dem Internet heraus. Das wirkt auch gegen Schwachstellen ausserhalb des REST-Servers und gegen Überlastung.
Der Router leitet den Port des REST-Servers aus dem Internet auf den OBS-Server weiter. Für die Zertifikatserneuerung mit der Prüfart http-01 wird zusätzlich Port 80 weitergeleitet.

'''Vorteile'''
* Die einfachste Einrichtung, es wird keine weitere Komponente gebraucht.
* Die App funktioniert überall, ohne dass die Nutzer etwas tun müssen.
* Der REST-Server sieht die IP-Adresse jedes Geräts. Alle Schutzmechanismen des REST-Servers, auch Host-Beschränkung und Rate-Limit, arbeiten damit je Gerät.

'''Nachteile'''
* Der OBS-Server mit der Datenbank ist direkt aus dem Internet erreichbar. Die [[#Schutz durch den REST-Server|Schutzmechanismen des REST-Servers]] greifen, eine zusätzliche Schicht davor gibt es aber nicht.
* Mit der Prüfart http-01 ist zusätzlich Port 80 weitergeleitet. Mit der Prüfart dns-01 entfällt das.

== Reverse-Proxy ==
Ein Reverse-Proxy, zum Beispiel in einer DMZ oder als Funktion der Firewall, nimmt HTTPS auf Port 443 an. Er prüft die Anfrage und reicht sie über eine eigene, ebenfalls verschlüsselte Verbindung an den REST-Server weiter.

'''Vorteile'''
* Der OBS-Server ist aus dem Internet nicht erreichbar, nur der Proxy.
* Am Proxy lassen sich Anfragen nach Ihren Vorgaben filtern, drosseln und protokollieren.
* Für die Nutzer der App ändert sich nichts.
* Das öffentliche Zertifikat liegt am Proxy. Die Zertifikatserneuerung des REST-Servers wird nicht gebraucht.

'''Nachteile'''
* Der Proxy muss betrieben und gepflegt werden.
* Der REST-Server sieht als Absender nur den Proxy. Die Host-Beschränkung eines Zugangs kann keine Geräte unterscheiden, und Anfragen ohne API-Key teilen sich einen Zähler des Rate-Limits. Die IP-Adresse des Geräts steht nur im Protokoll, wenn der Proxy den Header ''X-Forwarded-For'' setzt.

Die Einrichtung beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].

== VPN ==
Die Geräte verbinden sich per VPN mit dem Netz, in dem der OBS-Server steht. Die App spricht durch den Tunnel per HTTPS mit dem REST-Server. Aus dem Internet ist nur das VPN-Gateway erreichbar.

'''Vorteile'''
* Für den REST-Server ist kein Port aus dem Internet offen.
* Nur Geräte mit VPN-Zugang erreichen den REST-Server.
* Setzt das VPN-Gateway die Adressen nicht um, sieht der REST-Server die VPN-Adresse jedes Geräts.

'''Nachteile'''
* Jedes Gerät braucht einen VPN-Client und einen eigenen Zugang. Ohne zentrale Geräteverwaltung schalten die Nutzer das VPN von Hand ein. Ist es aus, meldet die App, dass der Server nicht erreichbar ist.
* Ein VPN-Zugang öffnet den Weg ins Netz. Beschränken Sie ihn auf die Adresse und den Port des REST-Servers.
* Das Zertifikat lässt sich nur mit der Prüfart dns-01 erneuern, weil die Zertifizierungsstelle den Server nicht erreicht.
* Der Name des REST-Servers muss auf dem Gerät auf die interne Adresse zeigen. Das geht über einen DNS-Server, den das VPN mitliefert, oder über einen öffentlichen DNS-Eintrag mit der internen Adresse. Manche Router verwerfen solche Antworten als Schutz gegen DNS-Rebinding; dann löst der Name in diesem Netz nicht auf.

Das Zertifikat richten Sie wie unter [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] beschrieben mit der Prüfart dns-01 ein.

== Entscheidungshilfe ==
* '''Keine eingehende Verbindung zum OBS-Server erlaubt, DMZ oder Firewall mit Proxy-Funktion vorhanden:''' Reverse-Proxy.
* '''Geräte werden zentral verwaltet oder ein VPN ist ohnehin im Einsatz:''' VPN.
* '''Kleine Installation ohne Vorgaben der IT:''' Direkte Portfreigabe, möglichst mit der Prüfart dns-01, damit Port 80 geschlossen bleibt.

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]]
* [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]]

OBS/Kostenpflichtige Module/RESTServer

2026-10-26T09:31:38Z

MINERVA-Rademacker: Weiterführende Seiten: Öffentliche Freigabe und Zertifikatserneuerung ergänzt [Volltext ersetzt]

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

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.

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

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''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===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''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)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''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)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''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.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''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.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''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:

{| 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-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| 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:

# 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"
! Anfrage !! Antwort
|-
| <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
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
|-
| Gepackter Körper bei einem Datei-Upload || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
|-
| Entpackter Körper über '''10 MB''' || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|}

{{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:

* '''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"
! Grenze !! Wert !! Bedeutung
|-
| Leerlauf || '''10 Sekunden''' || Passiert auf der Verbindung so lange nichts, wird sie geschlossen
|-
| Anfragen je Verbindung || '''100''' || Danach schliesst der Server geordnet, der Client baut neu auf
|}

Beides ist für den Konsumenten unkritisch: Eine geschlossene Verbindung ist kein
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 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 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:

* 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"
! Befehl !! Wirkung
|-
| ''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
|-
| ''1'' … ''9'' || Auswahl im Kopfbereich - kürzer als ''show'' für die gerade sichtbaren Anfragen. Mit ''mouse on'' auch per Klick
|-
| ''ps'' || Listet die gerade laufenden Anfragen auf
|-
| ''level <stufe>'' || Anzeigestufe des Live-Logs: ''quiet'' , ''normal'' oder ''debug''. Ohne Parameter wird die aktuelle Stufe genannt
|-
| ''filter <ausdruck>'' || Blendet aus, was nicht passt: ''path=<text>'', ''account=<name>'', ''status>=<code>''. ''filter aus'' hebt die Einschränkung auf
|-
| ''panel on|off'' || Fixierten Kopfbereich ein-/ausschalten. '''Ausgeschaltet''' lässt sich der Rückblick-Puffer des Konsolenfensters wieder scrollen
|-
| ''mouse on|off'' || Klick-Auswahl im Kopfbereich. '''Eingeschaltet''' ist das Markieren von Text mit der Maus nicht mehr möglich
|-
| ''help'' / ''?'' || Zeigt diese Liste in der Konsole
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

{{Hinweis|Der Anzeigefilter wirkt '''nur auf die Anzeige'''. Was die Konsole
ausblendet, steht vollständig in RESTSRV_PROTO - es geht nichts verloren.}}

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

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]] - Portfreigabe, Reverse-Proxy oder VPN im Vergleich
* [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]] - automatische Zertifikate über http-01 oder dns-01
* [[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/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[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]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-10-26T09:31:37Z

MINERVA-Rademacker: Verweise auf Zertifikatserneuerung und Öffentliche Freigabe ergänzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|automatische Zertifikatserneuerung]]. Wie der Server von aussen erreichbar wird und welche Variante sich eignet, beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]].

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Betrieb hinter einem Reverse-Proxy==

Läuft der REST-Server auf dem OBS-Server, soll dieser Server meist nicht direkt aus dem Internet erreichbar sein. Vor- und Nachteile gegenüber Portfreigabe und VPN beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]. Dann nimmt ein Reverse-Proxy die Anfragen entgegen, zum Beispiel in einer DMZ oder als Funktion der Firewall, und reicht sie an den REST-Server weiter. Von aussen ist nur der Proxy erreichbar.

Am Proxy und im Netz richten Sie ein:

* '''Öffentlicher Name:''' zeigt auf die öffentliche IP-Adresse des Proxys.
* '''Zertifikat:''' Der Proxy braucht ein öffentlich gültiges Zertifikat für diesen Namen. Die automatische Zertifikatserneuerung des REST-Servers wird nicht benötigt.
* '''Weiterleitung:''' Der Proxy leitet per HTTPS an <code>https://<OBS-Server>:<Port></code> weiter. Für diese Strecke genügt am REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut.
* '''Header:''' Alle HTTP-Methoden und Header unverändert durchreichen, insbesondere ''Authorization'', ''apikey'' und ''Idempotency-Key''. Antworten nicht zwischenspeichern. Den Header ''X-Forwarded-For'' mit der IP-Adresse des Konsumenten setzen.
* '''Anfragegrösse:''' Die maximale Anfragegrösse am Proxy darf nicht unter der Upload-Grenze der Endpunkte liegen.
* '''Firewall:''' Den Port des REST-Servers intern nur für den Proxy freigeben.

Hinter dem Proxy verhält sich der REST-Server so:

* Protokoll und Konsole zeigen als Host die IP-Adresse des Proxys und hängen den Wert von ''X-Forwarded-For'' als <code>[xff=…]</code> an.
* Die [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]] eines Zugangs kann keine einzelnen Konsumenten unterscheiden.
* Beim [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Rate-Limit je Profil|Rate-Limit]] teilen sich alle Konsumenten ohne API-Key einen Zähler.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-10-26T09:31:36Z

MINERVA-Rademacker: Zertifikatserneuerung auf eigene Seite verlagert, Felder der Registerkarte DNS-Prüfung ergänzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| zusätzliche Infos || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS-Modus aktiv || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Zertifikat (cert) || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Schlüssel (key) || PEM-Inhalt des privaten Schlüssels
|-
| Root-Zertifikat (ca) || PEM-Inhalt des CA-Zertifikats, gegen das '
|-
| Rate-Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Erfolgsanfragen || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Fehlanfragen || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Anfragen || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| max. Anfragen || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|-
| keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
|}

{{Hinweis|''max. Verbindungen'' und ''max. Anfragen'' sind die beiden
'''Lastgrenzen''' des Profils. Davon zu unterscheiden sind die festen Grenzen der
persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -,
die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe
[[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Persistente
Verbindungen.}}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Zertifikat + Schlüssel || Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
|-
| '''mTLS''' || Zertifikat + Schlüssel + Root-Zert. || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''HSTS:''' Jede Antwort eines TLS-Profils trägt ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse damit ein Jahr lang nur noch über HTTPS an. Beim Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
* '''Rotation:''' Bei '''automatischer Erneuerung''' tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
==Automatische Zertifikatserneuerung==

Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Prüfarten, Voraussetzungen, Einrichtung, Ablauf und Konsolenbefehle beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung|Zertifikatserneuerung]].

===Felder===

Registerkarte '''4 Zertifikaterneuerung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Automatische Erneuerung || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = nur für Testsysteme, siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Testbetrieb|Testbetrieb]]
|-
| Zertifikatsname (FQDN) || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
|-
| Kontakt bei der CA || Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
|-
| Zertifikat gültig bis || Ablaufdatum des aktiven Zertifikats
|-
| Testzertifikat aus Staging || Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
|-
| Zustand || ''idle'' = nichts zu tun, ''pending'' = Vorgang läuft, ''error'' = letzter Versuch fehlgeschlagen
|-
| Letzte Meldung || Ergebnis des letzten Vorgangs - im Störungsfall das erste Feld, in das Sie sehen
|-
| Gesperrt bis || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
|-
| Letzter Selbsttest am || Zeitpunkt der letzten Prüfung über das Testsystem der Zertifizierungsstelle
|-
| Selbsttest bestanden || Ergebnis dieser Prüfung
|}

Die Felder ab ''Zertifikat gültig bis'' füllt der Dienst selbst; sie dienen der Anzeige.

Registerkarte '''5 DNS-Prüfung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Prüfart || ''http-01 (Port 80)'' oder ''dns-01 (DNS-Eintrag)'', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung#Welche Prüfart?|Welche Prüfart?]]
|-
| DNS-Anbieter || Nur dns-01: ''acme-dns'', ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| Adresse (acme-dns) || Nur acme-dns: Adresse der Instanz, beginnt mit <code>https://</code>
|-
| Benutzer (acme-dns) || Nur acme-dns: Benutzer des Kontos. Bleiben Benutzer, Schlüssel und Name leer, legt der Dienst das Konto selbst an
|-
| Schlüssel / API-Token || acme-dns: Passwort des Kontos. Hetzner und Cloudflare: API-Token. IONOS: API-Schlüssel in der Form <code>Präfix.Secret</code>
|-
| Name des TXT-Eintrags || Leer = <code>_acme-challenge.<Zertifikatsname></code>. Bei CNAME-Delegation das Ziel des CNAME, bei acme-dns die ''fulldomain'' des Kontos
|}

{{Hinweis|Die Zugangsdaten stehen im Klartext im Server-Profil. Verwenden Sie Token, die nur die nötige Zone ändern dürfen.}}

==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Dasselbe gilt hinter einem Reverse-Proxy: Alle Anfragen kommen dort von der IP-Adresse
des Proxys, und alle Konsumenten ohne API-Key teilen sich einen Zähler. Der Header
''X-Forwarded-For'' ändert daran nichts, er wird nur protokolliert.

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Immer geprüft wird:

* Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
* Nr und Name sind eindeutig.
* Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
* Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.

Nur bei '''aktivem''' Profil zusätzlich:

* Ohne ''kein SSL'' und ohne automatische Erneuerung sind Zertifikat und Schlüssel vorhanden.
* Bei ''mTLS-Modus aktiv'' ist das Root-Zertifikat vorhanden.
* Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und ''kein SSL'' ist nicht gesetzt.

{{Hinweis|Ein '''nicht aktives''' Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.}}

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe

2026-10-26T09:31:23Z

MINERVA-Rademacker: Neue Seite: Varianten der öffentlichen Freigabe (Portfreigabe, Reverse-Proxy, VPN) als Entscheidungshilfe [Styleguide-Abweichung: Vergleichstabelle statt Seitenliste]

OBS/Kostenpflichtige Module/RESTServer/Zertifikatserneuerung

2026-10-26T09:31:23Z

MINERVA-Rademacker: Verweise auf Öffentliche Freigabe ergänzt

{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Zertifikatserneuerung =

Der REST-Server kann sein TLS-Zertifikat selbst bei der Zertifizierungsstelle Let's Encrypt beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen auf Ihrem Server und verlassen ihn nicht. Diese Seite beschreibt, wie Sie die Erneuerung je nach Netzaufbau einrichten.

{{Auf einen Blick|1=
* '''Zwei Prüfarten.''' http-01 prüft über Port 80, dns-01 über einen DNS-Eintrag und braucht keinen offenen Port.
* '''Selbsttest vorab.''' Vor dem ersten Zertifikat und danach wöchentlich prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle.
* '''Erneuerung ab 30 Tagen Restlaufzeit.''' Das bisherige Zertifikat bleibt als Rückfall erhalten.
* '''dns-01 braucht nur ausgehende Verbindungen''' und eignet sich damit für VPN und für Server ohne Portfreigabe.
}}

== Voraussetzungen ==
* Ein Name, auf den das Zertifikat lautet, zum Beispiel ''obs.kunde.de''. Platzhalter-Zertifikate (''*.kunde.de'') werden nicht unterstützt.
* Ein Server-Profil mit TLS, also ohne Haken '''kein SSL'''.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle (<code>acme-v02.api.letsencrypt.org</code> und für den Selbsttest <code>acme-staging-v02.api.letsencrypt.org</code>).
* Bei dns-01 zusätzlich ausgehende HTTPS-Verbindungen zur Schnittstelle des DNS-Anbieters bzw. zur acme-dns-Instanz.

=== Welche Prüfart? ===
{| class="wikitable"
! Prüfart !! Funktioniert, wenn !! Aus dem Internet erreichbar sein muss
|-
| http-01 || der Name öffentlich auf diesen Server zeigt und Port 80 von aussen auf ihn weitergeleitet ist || Port 80
|-
| dns-01 || sich der DNS-Eintrag <code>_acme-challenge.<Name></code> über eine Schnittstelle schreiben lässt, direkt oder über einen CNAME || nichts
|}

Welche Prüfart zu Ihrer [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|öffentlichen Freigabe]] passt:
* '''Direkte Portfreigabe:''' http-01 oder dns-01. Mit dns-01 bleibt Port 80 geschlossen.
* '''Reverse-Proxy:''' Das öffentliche Zertifikat liegt am Proxy, die Erneuerung im REST-Server wird nicht gebraucht.
* '''VPN:''' dns-01.

=== Wege bei dns-01 ===
Bei dns-01 fragt die Zertifizierungsstelle den TXT-Eintrag <code>_acme-challenge.<Name></code> ab. Der Dienst schreibt ihn vor der Prüfung und löscht ihn danach wieder. Dafür gibt es drei Wege:

{| class="wikitable"
! Weg !! Wann !! Einmalig beim DNS des Namens !! Einstellung '''DNS-Anbieter'''
|-
| Direkt beim Anbieter || Die Zone des Namens liegt bei Hetzner, Cloudflare oder IONOS || nichts, Sie brauchen nur ein API-Token || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf eine Zone bei einem Anbieter || Die Zone des Namens liegt bei einem anderen Anbieter, oder im REST-Server sollen keine Zugangsdaten zur eigenen Zone liegen || CNAME <code>_acme-challenge.<Name></code> auf einen Namen in einer Zone bei Hetzner, Cloudflare oder IONOS || ''Hetzner'', ''Cloudflare'' oder ''IONOS''
|-
| CNAME auf acme-dns || Eine acme-dns-Instanz steht zur Verfügung, im eigenen Betrieb oder bei einem Dienstleister || CNAME <code>_acme-challenge.<Name></code> auf die ''fulldomain'' des acme-dns-Kontos || ''acme-dns''
|}

Beim CNAME-Weg genügt beim DNS-Anbieter des Namens ein von Hand angelegter Eintrag, auch bei Anbietern ohne Schnittstelle. Der REST-Server bekommt dann nur Zugang zur Zone, auf die der CNAME zeigt.

{{Hinweis|Namen von DynDNS-Diensten (zum Beispiel ''…myfritz.net'') eignen sich in der Regel nicht als Zertifikatsname, weil sich dort keine eigenen Einträge anlegen lassen. Verwenden Sie einen Namen unter Ihrer eigenen Domain. Der DynDNS-Name bleibt davon unberührt, zum Beispiel für den Zugang zum VPN.}}

== Vorgehen ==
=== Gemeinsame Einstellungen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server → Server''' und öffnen Sie das Server-Profil.
# Stellen Sie auf der Registerkarte '''4 Zertifikaterneuerung''' das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb''.
# Tragen Sie im Feld '''Zertifikatsname (FQDN)''' den Namen ein, auf den das Zertifikat lauten soll.
# Tragen Sie unter '''Kontakt bei der CA''' eine E-Mail-Adresse ein. Die Zertifizierungsstelle schickt dorthin Warnungen, wenn ein Zertifikat abzulaufen droht.
# Richten Sie die Registerkarte '''5 DNS-Prüfung''' nach einem der folgenden Abschnitte ein und speichern Sie.
# Starten Sie den REST-Dienst neu.
}}

=== Prüfart http-01 ===
{{Schritte|1=
# Lassen Sie den Namen öffentlich auf die Adresse Ihres Internetanschlusses zeigen.
# Leiten Sie am Router Port 80 von aussen auf den OBS-Server weiter.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''http-01 (Port 80)''. Die übrigen Felder bleiben leer.
# Geben Sie in der Konsole des REST-Servers <code>cert test</code> ein.
}}

Port 80 darf auf dem OBS-Server von keinem anderen Dienst belegt sein, häufig ist das ein Webserver wie IIS. Der REST-Server öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.

=== Prüfart dns-01 direkt beim DNS-Anbieter ===
{{Schritte|1=
# Erstellen Sie beim Anbieter der Zone ein API-Token:
#* '''Hetzner:''' ein API-Token des Projekts mit Lese- und Schreibrecht in der Hetzner Console. Zonen in der früheren DNS-Konsole (dns.hetzner.com) werden nicht unterstützt.
#* '''Cloudflare:''' ein API-Token mit der Berechtigung, DNS zu bearbeiten, beschränkt auf die Zone.
#* '''IONOS:''' einen API-Schlüssel. Er besteht aus Präfix und Secret.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' im Feld '''Prüfart''' den Eintrag ''dns-01 (DNS-Eintrag)'' und im Feld '''DNS-Anbieter''' den Anbieter.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein, bei IONOS in der Form <code>Präfix.Secret</code>.
# Lassen Sie '''Name des TXT-Eintrags''' leer.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf eine Zone bei einem DNS-Anbieter ===
{{Schritte|1=
# Legen Sie in einer Zone bei Hetzner, Cloudflare oder IONOS einen Namen für die Prüfung fest, zum Beispiel ''obs-kunde.acme.example.de''. Einen Eintrag müssen Sie dort nicht anlegen.
# Legen Sie beim DNS-Anbieter Ihres Namens einen CNAME an: <code>_acme-challenge.obs.kunde.de</code> auf ''obs-kunde.acme.example.de''.
# Erstellen Sie ein API-Token für die Zone, in der das Ziel liegt, wie im vorigen Abschnitt beschrieben.
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den Anbieter dieser Zone.
# Tragen Sie unter '''Schlüssel / API-Token''' das Token ein.
# Tragen Sie unter '''Name des TXT-Eintrags''' das Ziel des CNAME ein, hier ''obs-kunde.acme.example.de''.
# Geben Sie in der Konsole <code>cert test</code> ein.
}}

=== Prüfart dns-01 mit CNAME auf acme-dns ===
{{Schritte|1=
# Wählen Sie auf der Registerkarte '''5 DNS-Prüfung''' die Prüfart ''dns-01 (DNS-Eintrag)'' und den DNS-Anbieter ''acme-dns''.
# Tragen Sie unter '''Adresse (acme-dns)''' die Adresse der Instanz ein. Sie beginnt mit <code>https://</code>.
# Lassen Sie '''Benutzer (acme-dns)''', '''Schlüssel / API-Token''' und '''Name des TXT-Eintrags''' leer und speichern Sie.
# Geben Sie in der Konsole <code>cert test</code> ein. Der Dienst legt das Konto bei acme-dns an und trägt Benutzer, Schlüssel und Name selbst ein. Unter '''Letzte Meldung''' steht danach der CNAME, den Sie anlegen müssen.
# Legen Sie beim DNS-Anbieter Ihres Namens diesen CNAME an: <code>_acme-challenge.<Name></code> auf die genannte ''fulldomain''.
# Geben Sie in der Konsole erneut <code>cert test</code> ein.
}}

{{Achtung|Leeren Sie die drei Felder später nicht. Der Dienst würde ein neues Konto mit einer neuen ''fulldomain'' anlegen, und der gesetzte CNAME zeigte ins Leere. Ein bestehendes Konto tragen Sie mit allen drei Angaben ein. Teilweise gefüllte Angaben weist die Maske beim Speichern ab.}}

=== Erstes Zertifikat holen ===
Ist der Selbsttest bestanden, holt der Dienst das Zertifikat bei der nächsten stündlichen Prüfung. Sofort geht es mit <code>cert renew</code> in der Konsole. Bis das erste Zertifikat da ist, kann sich kein Client mit dem Server-Profil verbinden.

=== Testbetrieb ===
{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client, Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen. Der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

== Ergebnis ==
Nach bestandenem Selbsttest ist auf der Registerkarte '''4 Zertifikaterneuerung''' der Haken '''Selbsttest bestanden''' gesetzt. Unter '''Letzte Meldung''' steht "Selbsttest bestanden - von aussen erreichbar" (http-01) bzw. "Selbsttest bestanden - DNS-Eintrag von der CA geprueft" (dns-01). Nach der Ausstellung zeigt '''Zertifikat gültig bis''' das Ablaufdatum, und <code>cert</code> in der Konsole zeigt den Stand je Profil.

Danach läuft die Erneuerung selbständig:
# '''Prüfung:''' Der Dienst sieht stündlich nach, ob etwas ansteht.
# '''Selbsttest:''' Einmal wöchentlich und nach jeder Änderung von Zertifikatsname, Prüfart, DNS-Anbieter oder Name des TXT-Eintrags prüft der Dienst den Weg über das Testsystem der Zertifizierungsstelle. Besteht der Test nicht, beantragt er kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet nur das betroffene Server-Profil neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht: eine, zwei, vier, acht und höchstens 24 Stunden. Das Feld '''Gesperrt bis''' zeigt, bis wann. <code>cert test</code> und <code>cert renew</code> in der Konsole wirken sofort, auch während der Sperre.

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort den Weg über das Testsystem der Zertifizierungsstelle. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

Bei dns-01 wartet der Dienst nach dem Schreiben des Eintrags 30 Sekunden und dann bis zu drei Minuten, bis der Eintrag über öffentliche DNS-Server sichtbar ist. Erst dann löst er die Prüfung aus.

== Wenn es nicht klappt ==
Die Meldungen stehen unter '''Letzte Meldung''' und im Protokoll des REST-Servers.

{| class="wikitable"
! Meldung !! Ursache
|-
| "Port 80 laesst sich nicht oeffnen - er ist belegt" || Ein anderer Dienst auf dem OBS-Server belegt Port 80, häufig IIS. Dienst abschalten oder die Prüfart dns-01 verwenden
|-
| "dns-01 ist eingestellt, aber kein DNS-Anbieter" || Auf der Registerkarte '''5 DNS-Prüfung''' ist kein DNS-Anbieter gewählt
|-
| "kein API-Token" || Das Feld '''Schlüssel / API-Token''' ist leer
|-
| "acme-dns: Konto unvollstaendig" || Von Benutzer, Schlüssel und Name des TXT-Eintrags ist nur ein Teil gefüllt
|-
| "Hetzner: keine Zone zu … im Projekt des Tokens" || Das Token gehört zu einem anderen Projekt, oder die Zone liegt noch in der früheren DNS-Konsole
|-
| "Cloudflare: keine Zone zu …, die das Token sehen darf" || Das Token ist nicht für diese Zone freigegeben
|-
| "IONOS: keine Zone zu … im Vertrag des Schluessels" || Der API-Schlüssel gehört zu einem anderen Vertrag
|-
| "… lehnt den TXT-Eintrag ab (HTTP 401)" oder "(HTTP 403)" || Das Token ist ungültig oder darf keine DNS-Einträge ändern
|-
| "… ist nach 210 Sekunden noch nicht ueberall sichtbar" || Der Eintrag ist über öffentliche DNS-Server nicht zu sehen. Meist fehlt der CNAME oder zeigt auf ein anderes Ziel als '''Name des TXT-Eintrags'''. Der Dienst löst die Prüfung trotzdem aus
|-
| "kein oeffentlicher DNS-Server erreichbar" || Ausgehendes DNS (Port 53) ist gesperrt. Der Dienst kann die Sichtbarkeit nicht prüfen und wartet fest 60 Sekunden
|-
| "acme-dns-Konto angelegt - jetzt CNAME … setzen" || Kein Fehler: Legen Sie den genannten CNAME an und geben Sie <code>cert test</code> ein
|}

== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Automatische Zertifikatserneuerung|Server-Profile: Felder der Zertifikatserneuerung]]
* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-10-26T08:22:19Z

MINERVA-Rademacker: Abschnitt Betrieb hinter einem Reverse-Proxy ergänzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die automatische Zertifikatserneuerung; dann genügen ein öffentlicher Name und eine Weiterleitung von Port 80 auf diesen Server. Soll der Server nicht direkt aus dem Internet erreichbar sein, siehe [[#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Betrieb hinter einem Reverse-Proxy==

Läuft der REST-Server auf dem OBS-Server, soll dieser Server meist nicht direkt aus dem Internet erreichbar sein. Dann nimmt ein Reverse-Proxy die Anfragen entgegen, zum Beispiel in einer DMZ oder als Funktion der Firewall, und reicht sie an den REST-Server weiter. Von aussen ist nur der Proxy erreichbar.

Am Proxy und im Netz richten Sie ein:

* '''Öffentlicher Name:''' zeigt auf die öffentliche IP-Adresse des Proxys.
* '''Zertifikat:''' Der Proxy braucht ein öffentlich gültiges Zertifikat für diesen Namen. Die automatische Zertifikatserneuerung des REST-Servers wird nicht benötigt.
* '''Weiterleitung:''' Der Proxy leitet per HTTPS an <code>https://<OBS-Server>:<Port></code> weiter. Für diese Strecke genügt am REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut.
* '''Header:''' Alle HTTP-Methoden und Header unverändert durchreichen, insbesondere ''Authorization'', ''apikey'' und ''Idempotency-Key''. Antworten nicht zwischenspeichern. Den Header ''X-Forwarded-For'' mit der IP-Adresse des Konsumenten setzen.
* '''Anfragegrösse:''' Die maximale Anfragegrösse am Proxy darf nicht unter der Upload-Grenze der Endpunkte liegen.
* '''Firewall:''' Den Port des REST-Servers intern nur für den Proxy freigeben.

Hinter dem Proxy verhält sich der REST-Server so:

* Protokoll und Konsole zeigen als Host die IP-Adresse des Proxys und hängen den Wert von ''X-Forwarded-For'' als <code>[xff=…]</code> an.
* Die [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]] eines Zugangs kann keine einzelnen Konsumenten unterscheiden.
* Beim [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Rate-Limit je Profil|Rate-Limit]] teilen sich alle Konsumenten ohne API-Key einen Zähler.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-10-26T08:22:18Z

MINERVA-Rademacker: Zertifikatserneuerung und Rate-Limit: Hinweise zum Betrieb hinter einem Reverse-Proxy ergänzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| zusätzliche Infos || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS-Modus aktiv || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Zertifikat (cert) || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Schlüssel (key) || PEM-Inhalt des privaten Schlüssels
|-
| Root-Zertifikat (ca) || PEM-Inhalt des CA-Zertifikats, gegen das '
|-
| Rate-Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Erfolgsanfragen || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Fehlanfragen || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Anfragen || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| max. Anfragen || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|-
| keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
|}

{{Hinweis|''max. Verbindungen'' und ''max. Anfragen'' sind die beiden
'''Lastgrenzen''' des Profils. Davon zu unterscheiden sind die festen Grenzen der
persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -,
die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe
[[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Persistente
Verbindungen.}}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Zertifikat + Schlüssel || Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
|-
| '''mTLS''' || Zertifikat + Schlüssel + Root-Zert. || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''HSTS:''' Jede Antwort eines TLS-Profils trägt ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse damit ein Jahr lang nur noch über HTTPS an. Beim Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
* '''Rotation:''' Bei '''automatischer Erneuerung''' tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
==Automatische Zertifikatserneuerung==

Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen dabei auf Ihrem Server und verlassen ihn nicht.

===Voraussetzungen===

* Ein öffentlicher Name, der von aussen auf diesen Server zeigt.
* '''Port 80''' ist von aussen auf diesen Server weitergeleitet. Darüber prüft die Zertifizierungsstelle, dass Sie den Namen betreiben. Der Dienst öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle sind erlaubt.

{{Hinweis|Port 80 wird unabhängig davon benötigt, auf welchem Port der REST-Server selbst lauscht. Die Prüfung der Zertifizierungsstelle beginnt immer auf Port 80.}}

{{Hinweis|Nimmt ein Reverse-Proxy die TLS-Verbindung von aussen an, braucht nur der Proxy das öffentliche Zertifikat. Die automatische Zertifikatserneuerung und die Weiterleitung von Port 80 auf den REST-Server entfallen dann. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].}}

===Felder===

Registerkarte '''4 Zertifikaterneuerung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Automatische Erneuerung || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = siehe Warnung unten
|-
| Zertifikatsname (FQDN) || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
|-
| Kontakt bei der CA || Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
|-
| Zertifikat gültig bis || Ablaufdatum des aktiven Zertifikats
|-
| Testzertifikat aus Staging || Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
|-
| Zustand || ''idle'' = nichts zu tun, ''pending'' = Vorgang läuft, ''error'' = letzter Versuch fehlgeschlagen
|-
| Letzte Meldung || Ergebnis des letzten Vorgangs - im Störungsfall das erste Feld, in das Sie sehen
|-
| Gesperrt bis || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
|-
| Letzter Selbsttest am || Zeitpunkt der letzten Erreichbarkeitsprüfung
|-
| Selbsttest bestanden || Ergebnis der letzten Erreichbarkeitsprüfung
|}

Die Felder ab ''Zertifikat gültig bis'' füllt der Dienst selbst; sie dienen der Anzeige.

===Ablauf===

Der Dienst sieht stündlich nach, ob etwas ansteht:

# '''Selbsttest:''' Einmal wöchentlich prüft der Dienst über das Testsystem der Zertifizierungsstelle, ob Ihr Server von aussen erreichbar ist. Besteht der Test nicht, beantragt der Dienst kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet '''nur das betroffene Server-Profil''' neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht - eine, zwei, vier, acht und höchstens 24 Stunden. Das verhindert, dass ein dauerhafter Fehler das Anfragekontingent der Zertifizierungsstelle aufbraucht.

===Befehle in der Konsole===

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort, ob der Server von aussen erreichbar ist. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

===Testbetrieb===

{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client - Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen; der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Dasselbe gilt hinter einem Reverse-Proxy: Alle Anfragen kommen dort von der IP-Adresse
des Proxys, und alle Konsumenten ohne API-Key teilen sich einen Zähler. Der Header
''X-Forwarded-For'' ändert daran nichts, er wird nur protokolliert.

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Immer geprüft wird:

* Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
* Nr und Name sind eindeutig.
* Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
* Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.

Nur bei '''aktivem''' Profil zusätzlich:

* Ohne ''kein SSL'' und ohne automatische Erneuerung sind Zertifikat und Schlüssel vorhanden.
* Bei ''mTLS-Modus aktiv'' ist das Root-Zertifikat vorhanden.
* Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und ''kein SSL'' ist nicht gesetzt.

{{Hinweis|Ein '''nicht aktives''' Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.}}

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-10-26T08:22:18Z

MINERVA-Rademacker: Host-Beschränkung und RESTSRV_TOKEN: Verhalten hinter einem Reverse-Proxy ergänzt (rt_ip_fwd) [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Ein Wildcard-Zugang eignet
sich deshalb für Artefakte, die für jeden bestimmt sind (Test-APK, Handbuch),
'''nicht''' für Kundenbelege. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].}}

{{Hinweis|Bei einem Wildcard-Zugang sollte ''CORS-Origin'' '''leer''' bleiben.
Ein ''*'' dort wirkt auf die Preflight-Antwort '''aller''' Zugänge (siehe unten);
ein Download über die Adresszeile des Browsers sendet ohnehin kein ''Origin'',
CORS greift dort also gar nicht.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

{{Hinweis|Hinter einem Reverse-Proxy ist die Remote-IP immer die des Proxys. Die Host-Beschränkung kann dort keine einzelnen Konsumenten unterscheiden. Der Header ''X-Forwarded-For'' wird dafür bewusst nicht ausgewertet, weil jeder Client ihn selbst setzen kann.}}

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

{{Achtung|Die Lebensdauer eines Refresh-Tokens ist nach oben auf '''372 Tage'''
begrenzt. Ein mit ''_OBS_JWT_REFRESH_EXP'' länger ausgestelltes Token wird bei der
Vorlage '''nicht mehr verifiziert''' und mit 401 abgewiesen - der Fehler fällt
also erst Monate später auf, beim ersten Erneuerungsversuch.}}

Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''', dem Code ''AUTH_FAILED'' und reicht den Text aus dem Feld
''error'' als ''error.message'' an den Client durch - der Konsument kann ihn also
direkt anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|''AUTH_FAILED'' unterscheidet die '''abgelehnte Anmeldung''' vom
''AUTH_EXPIRED'', das ein abgelaufenes oder gesperrtes Token liefert. Ein Client
sollte auf den Code reagieren und nicht auf den Text: Bei ''AUTH_FAILED'' gehört
die Anmeldemaske noch einmal vorgelegt, bei ''AUTH_EXPIRED'' erst ein Refresh
versucht.}}

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('all');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Woher ein Anmelder seine Identität bekommt==

'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.

Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.

Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt". Schickt ein Reverse-Proxy den Header
''X-Forwarded-For'' mit, steht dessen Wert zusätzlich in ''rt_ip_fwd''; ''rt_ip'' bleibt
die IP-Adresse der Verbindung.

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit '''CN=client-prod.kunde.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Kunde GmbH;CN=client-prod.kunde.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer

2026-10-26T08:22:17Z

MINERVA-Rademacker: Protokoll: Hinweis auf X-Forwarded-For hinter einem Reverse-Proxy ergänzt [Volltext ersetzt]

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

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.

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

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''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===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''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)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''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)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''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.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''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.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''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:

{| 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-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| 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:

# 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"
! Anfrage !! Antwort
|-
| <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
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
|-
| Gepackter Körper bei einem Datei-Upload || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
|-
| Entpackter Körper über '''10 MB''' || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|}

{{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:

* '''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"
! Grenze !! Wert !! Bedeutung
|-
| Leerlauf || '''10 Sekunden''' || Passiert auf der Verbindung so lange nichts, wird sie geschlossen
|-
| Anfragen je Verbindung || '''100''' || Danach schliesst der Server geordnet, der Client baut neu auf
|}

Beides ist für den Konsumenten unkritisch: Eine geschlossene Verbindung ist kein
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 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 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:

* 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"
! Befehl !! Wirkung
|-
| ''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
|-
| ''1'' … ''9'' || Auswahl im Kopfbereich - kürzer als ''show'' für die gerade sichtbaren Anfragen. Mit ''mouse on'' auch per Klick
|-
| ''ps'' || Listet die gerade laufenden Anfragen auf
|-
| ''level <stufe>'' || Anzeigestufe des Live-Logs: ''quiet'' , ''normal'' oder ''debug''. Ohne Parameter wird die aktuelle Stufe genannt
|-
| ''filter <ausdruck>'' || Blendet aus, was nicht passt: ''path=<text>'', ''account=<name>'', ''status>=<code>''. ''filter aus'' hebt die Einschränkung auf
|-
| ''panel on|off'' || Fixierten Kopfbereich ein-/ausschalten. '''Ausgeschaltet''' lässt sich der Rückblick-Puffer des Konsolenfensters wieder scrollen
|-
| ''mouse on|off'' || Klick-Auswahl im Kopfbereich. '''Eingeschaltet''' ist das Markieren von Text mit der Maus nicht mehr möglich
|-
| ''help'' / ''?'' || Zeigt diese Liste in der Konsole
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

{{Hinweis|Der Anzeigefilter wirkt '''nur auf die Anzeige'''. Was die Konsole
ausblendet, steht vollständig in RESTSRV_PROTO - es geht nichts verloren.}}

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

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[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/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[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]]

OBS/Kostenpflichtige Module/RESTServer

2026-10-05T06:34:37Z

MINERVA-Rademacker: Sicherheitsmerkmale um die automatische Zertifikatserneuerung ergaenzt [Volltext ersetzt]

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

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.

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

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''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===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''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)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''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)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''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.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''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.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''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:

{| 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-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| 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:

# 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"
! Anfrage !! Antwort
|-
| <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
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
|-
| Gepackter Körper bei einem Datei-Upload || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
|-
| Entpackter Körper über '''10 MB''' || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|}

{{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:

* '''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"
! Grenze !! Wert !! Bedeutung
|-
| Leerlauf || '''10 Sekunden''' || Passiert auf der Verbindung so lange nichts, wird sie geschlossen
|-
| Anfragen je Verbindung || '''100''' || Danach schliesst der Server geordnet, der Client baut neu auf
|}

Beides ist für den Konsumenten unkritisch: Eine geschlossene Verbindung ist kein
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 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 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.

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

* 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"
! Befehl !! Wirkung
|-
| ''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
|-
| ''1'' … ''9'' || Auswahl im Kopfbereich - kürzer als ''show'' für die gerade sichtbaren Anfragen. Mit ''mouse on'' auch per Klick
|-
| ''ps'' || Listet die gerade laufenden Anfragen auf
|-
| ''level <stufe>'' || Anzeigestufe des Live-Logs: ''quiet'' , ''normal'' oder ''debug''. Ohne Parameter wird die aktuelle Stufe genannt
|-
| ''filter <ausdruck>'' || Blendet aus, was nicht passt: ''path=<text>'', ''account=<name>'', ''status>=<code>''. ''filter aus'' hebt die Einschränkung auf
|-
| ''panel on|off'' || Fixierten Kopfbereich ein-/ausschalten. '''Ausgeschaltet''' lässt sich der Rückblick-Puffer des Konsolenfensters wieder scrollen
|-
| ''mouse on|off'' || Klick-Auswahl im Kopfbereich. '''Eingeschaltet''' ist das Markieren von Text mit der Maus nicht mehr möglich
|-
| ''help'' / ''?'' || Zeigt diese Liste in der Konsole
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

{{Hinweis|Der Anzeigefilter wirkt '''nur auf die Anzeige'''. Was die Konsole
ausblendet, steht vollständig in RESTSRV_PROTO - es geht nichts verloren.}}

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

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[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/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[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]]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-10-05T06:34:37Z

MINERVA-Rademacker: Automatische Zertifikatserneuerung als Alternative ergaenzt; Angaben zu Root-Zertifikat und Feldbezeichnungen richtiggestellt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die automatische Zertifikatserneuerung; dann genügen ein öffentlicher Name und eine Weiterleitung von Port 80 auf diesen Server.

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-10-05T06:34:36Z

MINERVA-Rademacker: Abschnitt zur automatischen Zertifikatserneuerung ergaenzt; Root-Zertifikat richtiggestellt (nur bei mTLS, nicht Teil der Serverkette); Feldbezeichnungen an die Maske angeglichen [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Server-Profile=

Ein '''Server''' im REST-Modul ist ein eigenständiges TLS-Profil mit einer eigenen HTTP-Server-Instanz. In OBS können beliebig viele Server-Profile parallel betrieben werden, jedes mit eigenem Modus, eigenen Zertifikaten und eigenen Bindungen.

Typische Einsatzfälle für mehrere Profile:

* Ein '''Public-Profil''' mit Standard-TLS auf Port 443 für externe Konsumenten.
* Ein '''Internal-mTLS-Profil''' auf einem internen Port für Microservices, die zwingend ein Client-Zertifikat vorlegen müssen.
* Ein '''Debug-Profil''' mit Plain-HTTP auf 127.0.0.1, ausschliesslich für lokale Tests.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Server'''

==Felder des Server-Profils==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Nr || Eindeutige Nummer 1-99, einmalig vergeben, kann später nicht mehr geändert werden
|-
| Name || Sprechender Name, eindeutig - erscheint in Protokoll, Statistik und Endpunkt-Zuordnung
|-
| Aktiv || Profil wird beim Start des REST-Dienstes geladen. Inaktive Profile starten nicht
|-
| zusätzliche Infos || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS-Modus aktiv || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Zertifikat (cert) || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Schlüssel (key) || PEM-Inhalt des privaten Schlüssels
|-
| Root-Zertifikat (ca) || PEM-Inhalt des CA-Zertifikats, gegen das '
|-
| Rate-Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Erfolgsanfragen || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Fehlanfragen || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Anfragen || Erlaubte Anfragen des gesamten Profils je Fenster. Leer/0 = Standard 600
|-
| max. Verbindungen || Obergrenze gleichzeitiger '''Verbindungen''' (<code>rsv_max_conn</code>). Leer/0 = unbegrenzt. Sie deckt auch laufende Datei-Downloads ab, weil der Platz erst beim Trennen frei wird. Bei Überschreitung trennt der Server '''ohne HTTP-Antwort''' - der Wert gehört deutlich über den Normalbetrieb, als Reissleine
|-
| max. Anfragen || Obergrenze gleichzeitig '''verarbeiteter Anfragen''' (<code>rsv_max_parallel</code>). Leer/0 = unbegrenzt. Bei Überschreitung antwortet der Server '''503''' mit <code>Retry-After</code>, der Client darf es also gleich erneut versuchen
|-
| keine Kompression || Antworten dieses Profils werden '''nicht''' gepackt (<code>rsv_no_gzip</code>). Ohne Haken packt der Server JSON- und Textantworten ab 1024 Byte mit gzip, sofern der Client sie über <code>Accept-Encoding</code> annimmt. Der Haken betrifft nur die Antwortrichtung - komprimierte '''Anfragen''' nimmt der Server weiterhin entgegen
|}

{{Hinweis|''max. Verbindungen'' und ''max. Anfragen'' sind die beiden
'''Lastgrenzen''' des Profils. Davon zu unterscheiden sind die festen Grenzen der
persistenten Verbindungen - 10 Sekunden Leerlauf, 100 Anfragen je Verbindung -,
die nicht der Last dienen, sondern der Hygiene und nicht einstellbar sind. Siehe
[[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Persistente
Verbindungen.}}

Die Inhalte der Zertifikate werden direkt in OBS als Text gespeichert. Zur Laufzeit schreibt der Server die PEM-Inhalte für den Bruchteil einer Sekunde in ein Temp-Verzeichnis, damit OpenSSL sie beim Start lesen kann; danach werden die Temp-Dateien sofort wieder gelöscht.

==Modi==

{| class="wikitable"
! Modus !! Voraussetzungen !! Anwendung
|-
| '''Standard-TLS''' || Zertifikat + Schlüssel || Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
|-
| '''mTLS''' || Zertifikat + Schlüssel + Root-Zert. || Maschine-zu-Maschine-Kommunikation, in der jeder Client mit Cert validiert wird
|-
| '''Plain-HTTP''' || Haken ''kein SSL'' || Ausschliesslich lokale Tests. Erkennt TLS-Versuche auf dem Plain-Port und trennt sie direkt
|}

Beide Richtungen werden erkannt: Eine '''unverschlüsselte Anfrage an einen
TLS-Port''' (''http'' statt ''https'') beantwortet der Server mit '''HTTP 400'''
und einem Klartext-Hinweis. Die Abweisung erfolgt '''vor''' Authentifizierung,
Rate-Limit und Endpunkt-Skript - ein falsch konfigurierter Client löst also
keine Verarbeitung aus.

{{Hinweis|Bei Standard-TLS und mTLS fährt der Server ohne Zertifikat und Schlüssel gar nicht erst hoch. Bei aktiver Erneuerung trägt der Dienst beides selbst ein. Plain-HTTP umgeht TLS komplett und ist nicht für Produktivumgebungen geeignet.}}

==TLS-Version, Cipher und Zertifikats-Rotation==

* '''TLS-Version:''' Der Server erzwingt '''TLS 1.2'''. Die Cipher-Liste ist auf ECDHE-Schlüsselaustausch (Forward Secrecy) mit AEAD-Verfahren (AES-GCM, ChaCha20-Poly1305) beschränkt; CBC, statisches RSA-KEX und DHE sind ausgeschlossen.
* '''HSTS:''' Jede Antwort eines TLS-Profils trägt ''Strict-Transport-Security: max-age=31536000; includeSubDomains''. Ein Browser spricht die Adresse damit ein Jahr lang nur noch über HTTPS an. Beim Profil ''Kein SSL'' wird der Header bewusst '''nicht''' gesetzt - der Browser würde ihn sonst speichern und die Erzwingung auch auf produktive Sitzungen anwenden.
* '''Rotation:''' Bei '''automatischer Erneuerung''' tauscht der Dienst das Zertifikat selbst und startet dabei nur das betroffene Server-Profil neu; die übrigen Profile und der Dienst laufen weiter. Bei manueller Pflege ändern Sie die PEM-Inhalte und starten den REST-Dienst neu - bis dahin läuft das alte Zertifikat weiter.
* '''Certificate-Pinning:''' Mobile Clients können den Server-Public-Key pinnen. Zertifikatswechsel daher '''rechtzeitig ankündigen''' und mit einem '''Backup-Pin''' vorbereiten - der neue Pin muss vor dem Wechsel in einer Client-Version ausgerollt sein, sonst sperrt sich die App aus.
==Automatische Zertifikatserneuerung==

Der REST-Server kann sein TLS-Zertifikat selbst bei einer Zertifizierungsstelle beantragen und vor Ablauf erneuern. Zertifikat und privater Schlüssel entstehen dabei auf Ihrem Server und verlassen ihn nicht.

===Voraussetzungen===

* Ein öffentlicher Name, der von aussen auf diesen Server zeigt.
* '''Port 80''' ist von aussen auf diesen Server weitergeleitet. Darüber prüft die Zertifizierungsstelle, dass Sie den Namen betreiben. Der Dienst öffnet den Port nur für die Dauer der Prüfung und schliesst ihn danach wieder.
* Ausgehende HTTPS-Verbindungen zur Zertifizierungsstelle sind erlaubt.

{{Hinweis|Port 80 wird unabhängig davon benötigt, auf welchem Port der REST-Server selbst lauscht. Die Prüfung der Zertifizierungsstelle beginnt immer auf Port 80.}}

===Felder===

Registerkarte '''4 Zertifikaterneuerung''':

{| class="wikitable"
! Feld !! Beschreibung
|-
| Automatische Erneuerung || ''deaktiviert'' = aus. ''Produktivbetrieb'' = der Dienst beantragt und erneuert das Zertifikat selbst. ''Testbetrieb'' = siehe Warnung unten
|-
| Zertifikatsname (FQDN) || Der Name, auf den das Zertifikat ausgestellt wird. Pflicht, sobald die Erneuerung aktiv ist
|-
| Kontakt bei der CA || Optional. Die Zertifizierungsstelle schickt an diese Adresse Warnungen, wenn ein Zertifikat abzulaufen droht
|-
| Zertifikat gültig bis || Ablaufdatum des aktiven Zertifikats
|-
| Testzertifikat aus Staging || Gesetzt, wenn das aktive Zertifikat aus dem Testbetrieb stammt
|-
| Zustand || ''idle'' = nichts zu tun, ''pending'' = Vorgang läuft, ''error'' = letzter Versuch fehlgeschlagen
|-
| Letzte Meldung || Ergebnis des letzten Vorgangs - im Störungsfall das erste Feld, in das Sie sehen
|-
| Gesperrt bis || Nach einem Fehlschlag wartet der Dienst bis zu diesem Zeitpunkt, bevor er es erneut versucht
|-
| Letzter Selbsttest am || Zeitpunkt der letzten Erreichbarkeitsprüfung
|-
| Selbsttest bestanden || Ergebnis der letzten Erreichbarkeitsprüfung
|}

Die Felder ab ''Zertifikat gültig bis'' füllt der Dienst selbst; sie dienen der Anzeige.

===Ablauf===

Der Dienst sieht stündlich nach, ob etwas ansteht:

# '''Selbsttest:''' Einmal wöchentlich prüft der Dienst über das Testsystem der Zertifizierungsstelle, ob Ihr Server von aussen erreichbar ist. Besteht der Test nicht, beantragt der Dienst kein Zertifikat.
# '''Erneuerung:''' Ab 30 Tagen Restlaufzeit beantragt der Dienst ein neues Zertifikat.
# '''Übernahme:''' Der Dienst prüft das neue Zertifikat, speichert es und bewahrt das bisherige als Rückfall auf. Anschliessend startet '''nur das betroffene Server-Profil''' neu.
# '''Rückfall:''' Startet das Profil mit dem neuen Zertifikat nicht, aktiviert der Dienst wieder das vorherige.

Nach einem Fehlschlag wartet der Dienst zunehmend länger, bevor er es erneut versucht - eine, zwei, vier, acht und höchstens 24 Stunden. Das verhindert, dass ein dauerhafter Fehler das Anfragekontingent der Zertifizierungsstelle aufbraucht.

===Befehle in der Konsole===

{| class="wikitable"
! Befehl !! Wirkung
|-
| <code>cert</code> || Zeigt je Profil Betriebsart, Ablaufdatum, Zustand und das Ergebnis des letzten Selbsttests
|-
| <code>cert test</code> || Prüft sofort, ob der Server von aussen erreichbar ist. Beantragt kein Zertifikat
|-
| <code>cert renew</code> || Stösst die Erneuerung sofort an, auch wenn sie noch nicht fällig ist
|}

===Testbetrieb===

{{Achtung|Im '''Testbetrieb''' beantragt der Dienst das Zertifikat beim Testsystem der Zertifizierungsstelle. Einem solchen Zertifikat vertraut '''kein''' Client - Anwendungen können sich danach nicht mehr mit diesem Server verbinden. Verwenden Sie den Testbetrieb ausschliesslich auf Testsystemen. Zurück in den Produktivbetrieb kommen Sie, indem Sie das Feld '''Automatische Erneuerung''' auf ''Produktivbetrieb'' stellen; der Dienst holt daraufhin sofort ein gültiges Zertifikat, auch wenn das Testzertifikat noch lange läuft.}}

==Rate-Limit je Profil==

Jedes Server-Profil führt '''eigene Zähler''' und kann '''eigene Schwellen''' haben.
Ein Profil, das gerade überrannt wird, bremst damit die anderen Profile nicht mit
aus - das Public-Profil und das interne mTLS-Profil sind voneinander unabhängig.

Gezählt wird pro Schlüssel, und der Schlüssel ist der '''API-Key''' des Zugangs.
Sendet ein Konsument keinen API-Key (Zugang mit ''*''), wird ersatzweise auf die
'''IP-Adresse''' gezählt.

{{Hinweis|Das ist der wichtigste Punkt bei mobilen Anwendungen: Sitzen alle
Benutzer hinter einer gemeinsamen Firmen-IP und sendet die App keinen eigenen
API-Key, teilen sich '''alle Benutzer einen Zähler'''. Mit den Standardwerten sind
das 10 Fehlversuche für den ganzen Betrieb pro Minute - nach ein paar falschen
Passworteingaben steht die Abteilung. Für solche Profile die Schwellen bewusst
höher setzen oder jedem Konsumenten einen eigenen API-Key geben.}}

Bleiben alle vier Felder leer (bzw. 0), gelten die Standardwerte. Die Werte werden
'''beim Start''' des REST-Dienstes gelesen - eine Änderung wird erst nach einem
Neustart wirksam.

==Validierung beim Speichern==

Immer geprüft wird:

* Nr und Name sind vergeben, Nr liegt zwischen 1 und 99.
* Nr und Name sind eindeutig.
* Eingetragene Zertifikate und Schlüssel liegen im PEM-Format vor.
* Ein eingetragener Zertifikatsname enthält keine Adresse, keinen Port und keine Leerzeichen.

Nur bei '''aktivem''' Profil zusätzlich:

* Ohne ''kein SSL'' und ohne automatische Erneuerung sind Zertifikat und Schlüssel vorhanden.
* Bei ''mTLS-Modus aktiv'' ist das Root-Zertifikat vorhanden.
* Bei aktiver Erneuerung ist der Zertifikatsname vergeben, und ''kein SSL'' ist nicht gesetzt.

{{Hinweis|Ein '''nicht aktives''' Profil dürfen Sie unvollständig speichern - es wird beim Start des Dienstes nicht geladen. Was Sie eintragen, wird trotzdem auf Plausibilität geprüft.}}

==Bindungen==

Eine Bindung ist die Kombination aus IP-Adresse und Port, auf der ein Server-Profil lauscht. Pro Server-Profil können mehrere Bindungen existieren, z.B. um die gleiche TLS-Konfiguration parallel auf 443 und 8443 anzubieten.

===Aufruf===

In der Server-Liste den gewünschten Server markieren und '''F6''' drücken. Es öffnet sich die zum Server gehörende Bindungs-Liste.

===Felder===

{| class="wikitable"
! Feld !! Beschreibung
|-
| Host || IP-Adresse oder Hostname, auf dem gelauscht wird. ''0.0.0.0'' = alle IPv4-Adressen; ''127.0.0.1'' = nur lokal; explizite IPs binden gezielt auf eine Netzwerkkarte
|-
| Port || TCP-Port (1-65535). 443/8443 für HTTPS, frei wählbar für Debug-Profile
|-
| Aktiv || Bindung wird beim Server-Start geladen
|-
| Standard|| Markiert die Standard-Bindung des Servers. Pro Server-Profil ist nur eine Standard-Bindung erlaubt
|}

===Wirksamkeit===

Bindungen werden ausschliesslich beim Start des REST-Dienstes geladen. Änderungen werden daher erst nach einem Neustart aktiv. Bis dahin laufen die alten Bindungen weiter.

==Listen-Funktionen==

In der Server-Liste:

* '''Einfg''' - neues Server-Profil
* '''Return''' - vorhandenes Profil bearbeiten
* '''F4''' - Sortierung wählen
* '''F6''' - Bindungs-Liste des markierten Servers

OBS/Kostenpflichtige Module/RESTServer/Datei-Upload

2026-09-25T09:28:34Z

MINERVA-Rademacker: Reader-Aufrufe statt _OBS_UPLOAD_-Felder, Idempotency-Key-Pflicht bei Uploads ergaenzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

= Datei-Upload =

Ein Endpunkt nimmt Dateien nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]). Dann gilt nicht
das JSON-Body-Limit von 10 MB, sondern die pro Endpunkt konfigurierte Grösse
(<code>re_upload_size</code>, Standard 25 MB; Überschreitung -> '''413''').

Diese Seite beschreibt die '''Übertragung''' - was ein Client senden muss und was
der Server antwortet. Was das '''Skript''' davon sieht, sind vier Aufrufe
(<code>oReader.UploadPath()</code>, <code>UploadName()</code>,
<code>UploadType()</code>, <code>UploadSha()</code>) und steht unter
[[OBS/Kostenpflichtige Module/RESTServer/Scripting#Datei-Uploads|Scripting]].
Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

{{Hinweis|Der Server legt die Datei in einem temporären Verzeichnis ab und
'''verschiebt sie nicht selbst'''. Übernimmt das Skript sie nicht an ihren
Zielort, bleibt sie dort liegen.}}

{{Achtung|Ein Upload läuft über ''POST'' und braucht deshalb - wie jeder
schreibende Aufruf - den Header <code>Idempotency-Key</code>. Fehlt er, antwortet
der Server mit '''400''' <code>IDEMPOTENCY_KEY_MISSING</code>, und zwar bevor eine
Datei entgegengenommen wird. Beim resumable Upload gehört er an '''jedes'''
Teilstück; wirksam wird er beim letzten, weil erst dort eine Antwort entsteht, die
sich speichern lässt. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz.}}

== Einfacher Upload (multipart/form-data) ==

Eine Datei pro Request. Name und Content-Type stammen aus der
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
Server speichert die erste Datei-Partie und ruft das Skript auf.

Die '''übrigen Partien''' des Formulars - alles ohne <code>filename=</code> -
liest das Skript über <code>oReader.Form('<name>')</code>. Der Wert ist UTF-8 und
auf 1024 Zeichen begrenzt, der Name auf Buchstaben, Ziffern und Unterstrich
reduziert. Zusatzangaben lassen sich damit im selben Request mitschicken, ohne sie
an die URL zu hängen:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cPfad : string;
cName : string;
cTyp : string;
cBemerk: string;
begin
cPfad := oReader.UploadPath();
cName := oReader.UploadName();
cTyp := oReader.UploadType();
cBemerk := oReader.Form('bemerkung'); // Formularfeld derselben Uebertragung

// ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...

oWriter.Str('status' , 'ok');
oWriter.Str('dateiname', cName);
oWriter.Status(201);
end;
</syntaxhighlight>

== Resumable/Chunked Upload (Content-Range) ==

Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
Header <code>Content-Range: bytes START-END/TOTAL</code>. Der Server hängt die
Chunks '''sequentiell''' an eine Session-Datei an und behandelt unvollständige
Uploads selbst - das Endpunkt-Skript läuft '''erst beim vollständigen Upload''',
und dann liefern ''oReader.UploadPath()'', ''UploadName()'' und ''UploadType()''
dasselbe wie beim einfachen Upload. Für die Teilstücke läuft es '''nicht'''.

Name und Content-Type sind im <code>Content-Range</code>-Protokoll nicht enthalten;
der Client liefert sie deshalb '''im ersten Chunk''' über den Header
<code>Upload-Metadata</code> (Format wie bei tus: kommagetrennte Paare
<code>schlüssel base64wert</code>, Werte Base64-kodiert):

<pre>
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>

Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird.
Folge-Chunks und Statusabfragen müssen die Metadaten nicht erneut senden.

Ablauf (vom Client gesteuert, der Server antwortet jeweils):

{| class="wikitable"
! Request !! Server-Antwort
|-
| Erster Chunk <code>Content-Range: bytes 0-1048575/5000000</code> + <code>Upload-Metadata</code> || '''308''' Resume Incomplete + Header <code>Upload-Id</code>, <code>Upload-Offset</code>, <code>Range</code>
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
|}

{| class="wikitable"
! Header !! Richtung !! Bedeutung
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
|-
| Upload-Id || Request/Response || Session-Kennung. Fehlt sie im ersten Request, erzeugt der Server eine und gibt sie zurück; alle Folge-Chunks müssen sie mitsenden.
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
|}

Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
entspricht'''. Bei Abweichung (doppelter Chunk, Lücke) wird nicht angehängt,
sondern der aktuelle ''Upload-Offset'' zurückgemeldet - der Client setzt ab dort
neu auf. Eine separate Statusabfrage ist für ein Resume daher nicht zwingend nötig.

Überschreitet ein Chunk bzw. die Gesamtgrösse das Limit (''re_upload_size''),
antwortet der Server mit '''413 Payload Too Large'''.

{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}

== Komprimierte Uploads ==

Ein Upload-Körper mit dem Header <code>Content-Encoding</code> wird mit '''415 Unsupported Media Type''' abgewiesen - bei beiden Verfahren, einfach wie chunked.

Der Grund ist nicht Bequemlichkeit. Bei einem chunked Upload bliebe offen, ob <code>Content-Range</code> die gepackten oder die rohen Bytes zählt, und die SHA256-Prüfsumme bezöge sich nach einem Entpacken auf eine andere Datei, als der Client gesendet hat. Etablierte Protokolle - tus, S3 Multipart, Google Resumable Upload, Azure Blob - behandeln Kompression aus demselben Grund als Eigenschaft der '''gespeicherten Datei''' und nicht der Übertragung.

Wer gepackt hochladen will, packt die Datei '''selbst''' und lädt sie als <code>export.csv.gz</code> hoch. Offsets, Prüfsumme und Wiederaufnahme stimmen dann, und das Endpunkt-Skript bekommt Name und Typ wie gewohnt über <code>oReader.UploadName()</code> und <code>oReader.UploadType()</code>.

OBS/Kostenpflichtige Module/RESTServer/Zugaenge

2026-09-25T09:28:33Z

MINERVA-Rademacker: Fehlercode AUTH_FAILED und Obergrenze der Refresh-Laufzeit ergaenzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Zugänge=

Ein '''Zugang''' (Account) ist der Kanal, über den ein externer Konsument den REST-Server anspricht. Er bündelt API-Key, Host-Beschränkung, CORS-Konfiguration, optionale JWT-Authentifizierung und optionale mTLS-Subject-Prüfung.

==Aufruf==

'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Zugänge'''

==Felder==

{| class="wikitable"
! Feld !! Beschreibung
|-
| Name || Sprechender Name, erscheint im Protokoll und der Statistik
|-
| Aktiv || Inaktive Zugänge werden bei der Authentifizierung mit 403 abgewiesen
|-
| API-Key || Eindeutiger Schlüssel, den der Konsument im HTTP-Header ''apikey'' senden muss. Per Schlüsselsymbol generierbar
|-
| Host || Optionaler Hostname oder IP-Adresse des Konsumenten. Stimmt die anfragende IP nicht überein, wird mit 403 abgelehnt
|-
| CORS-Origins || Liste erlaubter Origins für Browser-Aufrufe, mehrere durch '';'' getrennt. '''Leer heisst nicht „keine Einschränkung", sondern „kein Browser-Zugriff"''' - siehe unten
|-
| mTLS-Subject || Erwartete RDN-Komponente(n) im Client-Zertifikat-Subject, Komma-/Semikolon-getrennt (alle müssen vorkommen; nur sinnvoll bei mTLS-Servern)
|-
| JWT || Schalter, ob für diesen Zugang ein JWT-Token nötig ist
|-
| JWT-Endpunkt || Pfad, über den '''alle Token-Vorgänge''' laufen: Anmelden, Erneuern und Abmelden (z.B. ''oauth'' oder ''meineapp/dev/auth''). Verglichen wird der '''vollständige Pfad''', mehrstufige Angaben mit ''/'' sind also erlaubt
|-
| JWT-Key || Geheimer Schlüssel zur Signierung/Verifikation, per Schlüsselsymbol generierbar
|-
| JWT-Exp || Gültigkeitsdauer eines ausgestellten Access-Tokens in '''Minuten'''. Derselbe Wert wird dem Konsumenten in der Token-Antwort als ''expiresIn'' in '''Sekunden''' mitgeteilt und steht dem Endpunkt-Skript als ''_OBS_JWT_EXP_SEC'' zur Verfügung
|}

==API-Key==

Der API-Key ist die Basis-Authentifizierung. Der Client übergibt ihn im HTTP-Header:

apikey: abcd-efgh-ijkl-mnop-qrstuvwxyz12

Wird ein Aufruf ohne ''apikey''-Header gestellt, sucht der Server intern nach einem Zugang mit API-Key '''*''' - damit lassen sich (mit Vorsicht!) auch öffentliche Endpunkte ohne Authentifizierung realisieren.

{{Hinweis|Ein Zugang mit API-Key ''*'' sollte nur für bewusst freigegebene Endpunkte verwendet werden und immer in Kombination mit einer Host-Beschränkung oder CORS-Beschränkung betrieben werden.}}

{{Achtung|'''Nur für wirklich öffentliche Dateien.''' Ohne API-Key kennt der
Endpunkt weder Mandant noch Rolle - es gibt nichts, woran er eine Berechtigung
festmachen könnte ausser dem, was in der URL steht. Ein Wildcard-Zugang eignet
sich deshalb für Artefakte, die für jeden bestimmt sind (Test-APK, Handbuch),
'''nicht''' für Kundenbelege. Siehe
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].}}

{{Hinweis|Bei einem Wildcard-Zugang sollte ''CORS-Origin'' '''leer''' bleiben.
Ein ''*'' dort wirkt auf die Preflight-Antwort '''aller''' Zugänge (siehe unten);
ein Download über die Adresszeile des Browsers sendet ohnehin kein ''Origin'',
CORS greift dort also gar nicht.}}

==Host-Beschränkung==

Ist im Feld '''Host''' ein Wert hinterlegt, akzeptiert der Server Anfragen unter diesem Zugang nur dann, wenn die Remote-IP exakt diesem Host entspricht oder durch DNS-Auflösung auf diese IP zeigt. DNS-Auflösungen werden 5 Minuten gecached.

==CORS==

Soll ein Endpunkt aus einer Browser-Anwendung (Single-Page-App, JavaScript) heraus aufgerufen werden, muss das Origin der Anwendung in der CORS-Liste des Zugangs eingetragen sein.

Format der Liste:

https://app.kunde.de;https://test.kunde.de;https://localhost:8080

Ablauf:

# Browser sendet einen Preflight-Request (''OPTIONS''). Der REST-Server prüft das Origin gegen die globale Origin-Liste '''aller''' Accounts (Cache, TTL 60s) und antwortet mit 204 + CORS-Header, falls erlaubt.
# Der eigentliche Request wird gegen die Origin-Liste '''des aktuell verwendeten Zugangs''' geprüft.
# Stimmt das Origin nicht, wird mit 403 ''Origin nicht erlaubt für Account ...'' abgelehnt.

Der Preflight kann nicht zugangsbezogen prüfen: der Browser schickt dabei keinen
''apikey'' mit, der Zugang ist zu diesem Zeitpunkt unbekannt. '''Die Durchsetzung
liegt deshalb auf Schritt 2''', nicht auf dem Preflight. Praktische Folge: trägt
'''ein''' Zugang auf dem Server ein ''*'' in seiner Liste, antwortet jeder
Preflight mit ''Access-Control-Allow-Origin: *'' - auch für Zugänge mit engerer
Liste. Deren eigentliche Anfrage wird trotzdem gegen die eigene Liste geprüft.

Erlaubte Methoden: ''GET, POST, PUT, DELETE, PATCH'' (systemseitig festgelegt).

Bei den '''Anfrage-Headern''' spiegelt der Server im Preflight zurück, was der
Browser in ''Access-Control-Request-Headers'' angefragt hat. Damit sind eigene
Header eines Projekts - ''Idempotency-Key'', ''If-Match'', später
''Upload-Offset''/''Upload-Length'' - ohne Änderung am Server nutzbar. Fragt der
Preflight keine Header an, antwortet der Server mit der Liste
''Content-Type, apikey, Authorization, Accept''.

{{Hinweis|Die Header-Liste ist '''keine Schutzgrenze''' - das ist das Origin. Sie
sagt dem Browser nur, welche Header der Server versteht. Dazu kommt, dass die
Zugangsdaten dieser Schnittstelle in Headern stehen (''apikey'',
''Authorization'') und nicht in Cookies: es gibt also keine automatisch
mitgeschickte Berechtigung, die eine fremde Seite ausnutzen könnte.}}

===Was „leer" bedeutet===

{{Achtung|Ein '''leeres''' Feld CORS-Origins heisst '''nicht''' „keine
Einschränkung". Es heisst: '''jeder Aufruf mit ''Origin''-Header wird mit 403
abgelehnt'''. Für Clients '''ohne''' ''Origin''-Header - mobile Apps, Server,
curl - ändert das Feld gar nichts, sie werden nie gegen CORS geprüft.}}

Daraus ergeben sich drei sinnvolle Einstellungen:

{| class="wikitable"
! Feld !! Wirkung
|-
| leer || Kein Browser-Zugriff. Richtig für Zugänge, die nur von Apps oder Servern benutzt werden
|-
| konkrete Origins || Browser-Zugriff nur von diesen Seiten. Der Regelfall für Web-Anwendungen
|-
| ''*'' || Browser-Zugriff von überall. Wirkt zusätzlich auf die Preflight-Antwort aller anderen Zugänge - bewusst und sparsam verwenden
|}

Für eine Browser-Anwendung ist dieses Feld besonders wichtig, weil ihr API-Key
zwangsläufig im JavaScript liegt und damit öffentlich ist. Die Origin-Liste
verhindert dann, dass jemand den Key nimmt und von seiner eigenen Seite benutzt.
Sie ist allerdings kein Ersatz für eine Zugriffskontrolle: wer den Key hat,
umgeht CORS mit einem einzigen Aufruf ausserhalb des Browsers.

==JWT-Authentifizierung==

Wird ein Zugang mit aktiver JWT-Pflicht aufgerufen, sind die folgenden Phasen zu durchlaufen (Phase 3 nur bei genutztem Refresh).

'''Anmelden, Erneuern und Abmelden laufen über denselben Endpunkt''' - den im
Feld JWT-Endpunkt hinterlegten Pfad. Ein eigener Endpunkt fürs Abmelden ist
nicht nötig und wäre auch umständlicher: der JWT-Endpunkt greift '''vor''' der
Adressauflösung und braucht deshalb weder eine Zeile in ''RESTSRV_ENDPOINTS''
noch eine Berechtigung in ''RESTSRV_ACCESS''.

Unterschieden wird nach Verb und Token-Art:

{| class="wikitable"
! Aufruf !! Ablauf
|-
| ''POST'' ohne ''Authorization'' || Anmelden (Skript-Methode ''Authenticate'')
|-
| ''POST'' mit Bearer, Refresh-Token || Erneuern (Skript-Methode ''Refresh'')
|-
| ''DELETE'' mit Bearer, Access-Token || Abmelden (kein Skript nötig)
|-
| ''POST'' mit Bearer, Access-Token || '''401''' - unverändert
|}

{{Hinweis|Dass das Abmelden am Verb hängt und nicht allein an der Token-Art, ist
Absicht. Würde ein vorgelegtes Access-Token beim ''POST'' als Abmeldung gedeutet,
würde ein Client, der seine beiden Token verwechselt, den Anwender still
abmelden - statt das klare 401 zu bekommen, an dem der Fehler auffällt.}}

===Phase 1: Token-Bezug===

Der Konsument ruft den JWT-Endpunkt des Zugangs auf, z.B.:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Body: {"username":"...", "password":"..."}

Der Server führt das im Zugang hinterlegte '''Authentifizierungs-Skript''' aus (F7 in der Zugangs-Liste). Das Skript muss eine Prozedur ''Authenticate'' bereitstellen, die über den Writer schreibt:

* ''status'' = ''1'' bei Erfolg, ''9'' bei Misserfolg
* ''error'' = Fehlertext (bei status=9)
* ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'', ''_OBS_JWT_AUDIENCE'' für die JWT-Claims (optional)
* ''_OBS_JWT_CLAIM_<name>'' für beliebige Custom-Claims (z.B. Mandant ''tenant'', Rollen ''roles''); im Folge-Skript lesbar
* ''_OBS_JWT_REFRESH_ID'' (optional) löst die Ausstellung eines Refresh-Tokens aus; ''_OBS_JWT_REFRESH_EXP'' setzt dessen Lebensdauer in Minuten (Default 90 Tage)

{{Achtung|Die Lebensdauer eines Refresh-Tokens ist nach oben auf '''372 Tage'''
begrenzt. Ein mit ''_OBS_JWT_REFRESH_EXP'' länger ausgestelltes Token wird bei der
Vorlage '''nicht mehr verifiziert''' und mit 401 abgewiesen - der Fehler fällt
also erst Monate später auf, beim ersten Erneuerungsversuch.}}

Die Signatur lautet ''procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);'' - Details unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. Bei Erfolg signiert der Server einen Token (HS256, Issuer ''OBS REST-Server'', Lebenszeit gemäß JWT-Exp) und antwortet:

{"token": "eyJhbGciOi...",
"accessToken": "eyJhbGciOi...",
"expiresIn": 28800,
"serverTime": "2026-06-29T15:30:12+02:00"}

Zum Aufbau der Antwort:

* ''token'' und ''accessToken'' enthalten '''denselben''' Token. ''accessToken'' ist der Name, den die meisten Client-Bibliotheken erwarten; ''token'' bleibt für bestehende Konsumenten erhalten.
* ''expiresIn'' ist die Gültigkeit in '''Sekunden''' (JWT-Exp × 60).
* '''Alle weiteren Felder, die das Authenticate-Skript zurückgibt, werden mit ausgeliefert''' - mit Ausnahme von ''status'' und den ''_OBS_''-Steuerfeldern. So kann das Skript z.B. eine Benutzer-Id, den Mandanten oder Rollen direkt in die Anmelde-Antwort legen, ohne dass der Client dafür einen zweiten Aufruf braucht.

Beispiel mit Zusatzfeldern aus dem Skript:

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...", "accessToken": "eyJ...", "refreshToken": "eyJ...",
"expiresIn": 28800, "serverTime": "2026-06-29T15:30:12+02:00"}

Mit der Ausstellung legt der Server zu dem Token-Paar eine '''Sitzungszeile''' in
''RESTSRV_TOKEN'' an. Lässt sich diese Zeile nicht schreiben (Tabelle fehlt,
Datenbankproblem), wird '''kein Token ausgeliefert''': der Server antwortet mit
'''503''' und ''Retry-After''. Das ist bewusst von der abgelehnten Anmeldung
unterschieden - die Zugangsdaten waren in Ordnung, der Versuch darf wiederholt
werden.

Wird die Anmeldung abgelehnt (''status'' = 9), antwortet der Server mit
'''401 Unauthorized''', dem Code ''AUTH_FAILED'' und reicht den Text aus dem Feld
''error'' als ''error.message'' an den Client durch - der Konsument kann ihn also
direkt anzeigen. Die Formulierung liegt damit beim Skript.

{{Hinweis|''AUTH_FAILED'' unterscheidet die '''abgelehnte Anmeldung''' vom
''AUTH_EXPIRED'', das ein abgelaufenes oder gesperrtes Token liefert. Ein Client
sollte auf den Code reagieren und nicht auf den Text: Bei ''AUTH_FAILED'' gehört
die Anmeldemaske noch einmal vorgelegt, bei ''AUTH_EXPIRED'' erst ein Refresh
versucht.}}

{{Hinweis|Der durchgereichte Text ist für den Endanwender gedacht und sollte
keine internen Details verraten. „Benutzer oder Passwort ist falsch" ist eine gute
Meldung, „Kein Datensatz in BENUTZ mit b_name=meier" nicht.}}

===Phase 2: Token-Verwendung===

Bei allen folgenden Aufrufen sendet der Client den Token im ''Authorization''-Header:

GET https://api.meinserver.de/kalender/v1
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi...

Der Server verifiziert Signatur, Issuer, Ausstellzeitpunkt und Ablauf (Toleranz: 20 Sekunden Clock-Skew) und prüft anschliessend die '''Sitzung''' in ''RESTSRV_TOKEN''. Im Skript stehen die Claims als Parameter ''_OBS_JWT_ID'', ''_OBS_JWT_SUBJECT'' und ''_OBS_JWT_AUDIENCE'' zur Verfügung.

Die Sitzungsprüfung weist ein Token ab, das zu keiner Zeile gehört oder dessen
Sitzung gesperrt wurde - beides mit '''401''' und dem Code ''AUTH_EXPIRED''. Der
Grund steht jeweils im Protokoll '''RESTSRV_PROTO''' unter ''TokenStore: ...''.

{{Hinweis|Ein Token, das '''vor''' der Einführung dieser Prüfung ausgestellt
wurde, gehört zu keiner Sitzung und wird abgewiesen. Nach dem Update müssen sich
angemeldete Konsumenten also einmalig neu anmelden.}}

===Phase 3: Token erneuern (Refresh)===

Soll die App lange ohne Neuanmeldung arbeiten, stellt das Authenticate-Skript zusätzlich ein Refresh-Token aus (Feld ''_OBS_JWT_REFRESH_ID''). Zum Erneuern ruft der Client '''denselben JWT-Endpunkt''' auf, aber mit dem Refresh-Token im ''Authorization''-Header:

POST https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Refresh-Token)

Der Server erkennt am Bearer-Token den Refresh-Fall, verifiziert das Token (Signatur, Ablauf, ''token_use=refresh''), '''entwertet es in der Sitzung''' und ruft erst dann im selben Skript die Methode '''Refresh''' auf. Das Skript liefert nur noch die aktuellen Claims zurück - Rotation, Einmalgebrauch und Sperrliste erledigt der Server. Die Antwort ist ein rotiertes Paar ''{"token","accessToken","refreshToken","expiresIn","serverTime"}'' in '''derselben Sitzung'''.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal: einmal im Skript, einmal im
Server. Der Server sieht die Skript-Tabelle nicht, und das Skript sieht die
Sitzung nicht.}}

Verhalten bei einem bereits benutzten Refresh-Token:

{| class="wikitable"
! Lage !! Antwort !! Wirkung auf die Sitzung
|-
| Erneute Vorlage '''innerhalb von 60 Sekunden''' || 401 ''AUTH_EXPIRED'' || Keine. Das ist der Normalfall einer App, deren parallele Anfragen gleichzeitig in den Refresh laufen - eine gewinnt, die anderen sollen die vom Gewinner gespeicherten Token benutzen
|-
| Erneute Vorlage '''später''' || 401 ''AUTH_EXPIRED'' || Die '''gesamte Sitzung wird gesperrt'''. Das Token wurde kopiert oder wiederholt, ohne dass ein Gewinner es noch brauchen könnte; der Vorfall wird mit IP protokolliert
|}

Details und ein vollständiges Beispiel siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

===Phase 4: Abmelden (Logout)===

Abgemeldet wird mit einem '''DELETE''' auf denselben JWT-Endpunkt, das
Access-Token im ''Authorization''-Header:

DELETE https://api.meinserver.de/oauth/
Header: apikey: [API-KEY]
Authorization: Bearer eyJhbGciOi... (Access-Token)

HTTP/1.1 204 No Content

Der Server sperrt die '''ganze Sitzung''' - also auch die noch nicht
abgelaufenen Access-Token aller vorherigen Erneuerungen. '''Ein Skript ist dafür
nicht nötig''': es gibt keine Methode ''Logout'', der Vorgang läuft komplett in
der Engine. Damit funktioniert das Abmelden für jeden Zugang mit aktiver
JWT-Pflicht, ohne dass am Authentifizierungs-Skript etwas geändert wird.

* Ein wiederholter Aufruf ist unschädlich und bleibt '''204''' - auch wenn die Sitzung längst gesperrt ist.
* Ein abgelaufenes oder ungültiges Token ergibt '''401''' (es wird schon bei der Prüfung abgewiesen).
* Ein Refresh-Token statt des Access-Tokens ergibt '''401'''.
* Lässt sich die Sitzung nicht sperren, antwortet der Server '''503''' mit ''Retry-After'' - ein Client darf nicht glauben, er sei abgemeldet, während sein Token weiterläuft.

====Alle Geräte abmelden====

Der Fall „Gerät verloren" ist bewusst '''nicht''' am JWT-Endpunkt untergebracht:
er braucht eine fachliche Entscheidung darüber, wer das darf. Dafür gibt es das
''oWriter.JwtRevoke'', das jeder gewöhnliche Endpunkt aufrufen kann:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
// 'session' = nur diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('all');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

{{Hinweis|''all'' setzt voraus, dass das Authenticate-Skript ''_OBS_JWT_SUBJECT''
gesetzt hat. Ohne Subject lässt sich die Menge der Sitzungen nicht bestimmen, und
der Aufruf antwortet mit 503.}}

==Woher ein Anmelder seine Identität bekommt==

'''Diese Frage entscheidet das Skript des Zugangs, nicht der Server.''' Das
Authentifizierungs-Skript liegt je Zugang in <code>ra_jwt_script</code> - und
damit gilt für jede Anwendung ihre eigene Regel.

Das ist keine Kleinigkeit, sondern der Punkt, an dem sich zwei Anwendungen
unterscheiden. Ein Beispiel aus dem Betrieb: Ein Zugang für eine
Techniker-Anwendung lehnt jeden Benutzer ohne Mitarbeiterzuordnung
(<code>BENUTZ.b_mitarbeiter</code>) ab - '''bewusst''', denn ein Techniker ohne
Zuordnung bekäme eine leere Auftragsliste und würde den Fehler bei sich suchen.
Für einen Kundenzugang wäre genau dieselbe Regel falsch: sie träfe '''jeden'''
Anmelder.

Wer einen zweiten Zugang für eine andere Anwendung anlegt, prüft deshalb als
Erstes: Woraus besteht die Identität dieser Anmelder, und welche Ablehnung ist
für sie richtig? Ein kopiertes Skript bringt die Regel der anderen Anwendung
mit, und sie fällt erst auf, wenn sich der erste echte Anmelder nicht anmelden
kann.

==Sitzungen (RESTSRV_TOKEN)==

Je ausgestelltem Token-Paar entsteht eine Zeile. Sie enthält die Sitzung, die
Zeilenkennung, das Subject, die beiden Laufzeiten, IP und Trace-ID der Ausstellung
sowie die Kennzeichen „verbraucht" und „gesperrt".

* '''Rotation und Widerruf sind getrennt.''' Ein Refresh entwertet nur das Refresh-Token; der zugehörige Access-Token bleibt bis zu seinem Ablauf gültig. Sonst bekämen parallel laufende Anfragen ein 401, obwohl niemand abgemeldet ist.
* '''Die Sitzung überlebt die Rotation.''' Alle Paare einer Anmeldung tragen dieselbe Sitzungskennung - deshalb kann ein Logout sie gemeinsam sperren.
* '''Aufräumen läuft automatisch''' beim Serverstart und danach höchstens stündlich. Gelöscht wird nur, was nichts mehr entscheiden kann: Zeilen, deren Access- '''und''' Refresh-Laufzeit vorbei sind. Eine verbrauchte Zeile bleibt bis dahin stehen, weil sonst die Erkennung eines später vorgelegten gestohlenen Refresh-Tokens verloren ginge.
* '''Kein Eingriff nötig.''' Die Tabelle wird nicht gepflegt; sie ist Diagnose-Material. Alle Abweisungen stehen als ''TokenStore: ...'' in '''RESTSRV_PROTO'''.

==mTLS-Subject-Prüfung==

Wird im Feld '''mTLS-Subject''' ein Wert hinterlegt, prüft der Server zusätzlich zur Standard-mTLS-Validierung, ob der Subject-DN des (CA-validierten) Client-Zertifikats die hinterlegten '''RDN-Komponenten''' enthält. Verglichen wird jede Komponente '''vollständig''' (kein Substring-Match) und case-insensitiv; mehrere Komponenten werden durch Komma oder Semikolon getrennt und müssen '''alle''' im Subject vorkommen.

Beispiele für Subject-Strings im Cert (OneLine-DN):

/C=DE/O=Kunde GmbH/CN=client-prod.kunde.de
/C=DE/O=Kunde GmbH/CN=client-test.kunde.de

Mit '''CN=client-prod.kunde.de''' im Feld wird genau das prod-Cert akzeptiert, das test-Cert mit 401 abgewiesen. Da jede RDN-Komponente vollständig verglichen wird, matcht z.B. '''CN=client1''' nicht fälschlich auch '''CN=client10'''. Mehrere Bedingungen lassen sich mit Komma/Semikolon kombinieren, z.B. ''O=Kunde GmbH;CN=client-prod.kunde.de''.

==Listen-Funktionen==

In der Zugänge-Liste (allein):

* '''Einfg''' - neuer Zugang
* '''Return''' - Zugang bearbeiten
* '''F4''' - Sortierung
* '''F7''' - JWT-Authentifizierungs-Skript bearbeiten
* '''F8''' - Statistik für den Zugang

Aus der Endpunkt-Liste via F6 geöffnet (Auswahl für Berechtigung):

* '''F2''' - markierte Zugänge dem Endpunkt zuordnen
* '''F5''' - Zugang in der Liste markieren / Markierung aufheben

OBS/Kostenpflichtige Module/RESTServer/Server-Profile

2026-09-25T09:28:33Z

MINERVA-Rademacker: HSTS-Header und Abgrenzung der Verbindungsgrenzen ergaenzt [Volltext ersetzt]

OBS/Kostenpflichtige Module/RESTServer/Einrichtung

2026-09-25T09:28:33Z

MINERVA-Rademacker: Wartung der Idempotenz-Tabelle berichtigt, Stolperstein fehlender Idempotency-Key ergaenzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Einrichtung eines REST-Endpunktes=

Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.

==Vorbereitung==

# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, ggf. mit Chain), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten.

==Schritt 1: Server-Profil anlegen==

In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:

* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
* Auswahl des Modus:
** '''Standard-TLS''' (Default): Zertifikat + Key + Root-Zertifikat hinterlegen.
** '''mTLS''' aktivieren: zusätzlich CA-Root-Zertifikat hinterlegen, jeder Client muss ein gültiges Cert vorlegen.
** '''Kein SSL''' aktivieren: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.

Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.

Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].

==Schritt 2: Bindung anlegen==

Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:

* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).

==Schritt 3: REST-Dienst starten / neustarten==

Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.

==Schritt 4: Zugang anlegen==

Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:

* '''Name''' - erscheint im Protokoll und in der Statistik.
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

==Schritt 5: Endpunkt anlegen==

Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:

* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).

{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}

Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).

==Schritt 6: Zugang für den Endpunkt freischalten==

Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.

==Schritt 7: Funktionsprüfung==

Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):

curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]

Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.

==Schritt 8: Statistik und Protokoll prüfen==

* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.

==Wartung der Server-Tabellen==

Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:

{| class="wikitable"
! Tabelle !! Aufräumen
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
|}

==Häufige Stolpersteine==

* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

OBS/Kostenpflichtige Module/RESTServer/Scripting

2026-09-25T09:28:33Z

MINERVA-Rademacker: Idempotenz bei 5xx berichtigt (Schluessel wird freigegeben), Pflichtheader und Dateiantwort ergaenzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

=Anleitung für Endpunkt-Skripte=

Jede Anfrage an einen Endpunkt wird nach erfolgreicher Authentifizierung und Autorisierung an das hinterlegte Skript weitergegeben. Das Skript ist in Object Pascal geschrieben und greift auf die OBS-Bibliothek (DB-Zugriff, Hilfsfunktionen) zu.

==Sicherheitshinweise==

{{Hinweis|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Übergabeparameter dürfen niemals ungeprüft in SQL-Anweisungen eingebaut werden. Werte immer über ''DB_SQLVal'' bzw. Parameter-Bindings absichern, Eingabewerte gegen Whitelists prüfen.}}

* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
* Nur das zurückgeben, was der Konsument wirklich braucht - keine internen IDs, keine Sys-Felder, keine Passwörter.
* Bei Fehlern keine internen Details an den Konsumenten zurückgeben; stattdessen schreibt der Server ohnehin Detail-Einträge in '''RESTSRV_PROTO'''.

==Methoden-Signatur==

Pro HTTP-Methode wird im Skript eine gleichnamige '''Prozedur''' implementiert. Der Server ruft genau die Prozedur auf, die zur Methode des eingehenden Requests passt.

procedure Get (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);

Zwei Handles, kein Rückgabewert: '''oReader''' ist die Anfrage, '''oWriter''' die
Antwort. Beide erzeugt der Server, beide gehören ihm - im Skript wird nichts
angelegt und nichts freigegeben.

{{Achtung|'''DELETE hat keine Skript-Methode.''' <code>Delete</code> ist in der
Skriptsprache eine Standardprozedur (Löschen aus einer Zeichenkette); eine eigene
Prozedur dieses Namens lässt sich nicht übersetzen, und der Fehler nennt nur die
Zeile der Deklaration. Wer einen DELETE-Endpunkt braucht, legt die Methode unter
einem anderen Verb ab oder trennt sie in ein eigenes Skript.}}

Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Not Allowed''' (<code>METHOD_NOT_ALLOWED</code>) und nennt im Header
<code>Allow</code> die Verben, die dieses Skript tatsächlich anbietet - die Liste
stammt aus dem kompilierten Skript und kann deshalb nicht veralten:

HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT

Ein im Vertrag zugesagtes Verb braucht also seine Prozedur. Fehlt sie, ist das an
der Antwort sofort zu erkennen und '''kein''' Serverfehler.

==Die Anfrage lesen: oReader==

''oReader'' ist der einzige Zugang zur Anfrage - Query, Header, Formularfelder,
Pfadwerte, Token-Claims und Körper. Alles davon sind '''Zeichenketten''' oder
werden über einen typisierten Leser geholt.

{| class="wikitable"
! Aufruf !! Was er liefert
|-
| <code>oReader.Param('kundennr')</code> || Query-Parameter, POST-Parameter (form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet
|-
| <code>oReader.Path('uid')</code> || Wert eines Platzhalters aus dem Pfad-Template
|-
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung
|-
| <code>oReader.Claim('tenant')</code> || Custom-Claim des vorgelegten Tokens
|-
| <code>oReader.Subject()</code> || Subject des Tokens (''sub''-Claim)
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests
|-
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+02:00''
|-
| <code>oReader.HasBody()</code> || Wurde überhaupt ein JSON-Körper gesendet?
|}

Filterung durch den Server:

* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
* Werte, die von aussen kommen, können die reservierten Namen nicht besetzen.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.

Zugriff im Skript:

cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
// ...
end;

===Der Körper: Zugriff über Pfade===

Den JSON-Körper liest ''oReader'' über '''Pfade'''. Es gibt keine Unterobjekte im
Skript, keinen Cast, kein ''.Items[i]'' - und damit auch keine Lebensdauer, um die
sich jemand kümmern müsste.

{| class="wikitable"
! Aufruf !! Bedeutung
|-
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': war das Feld da? Fehlt es, bleibt die Variable unverändert
|-
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl
|-
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. '''Der Dezimalpunkt aus JSON wird richtig gelesen''' - kein ''StrTran'' mehr
|-
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean
|-
| <code>oReader.NumDef('rabatt', nWert, 0)</code> || wie ''Num'', mit Vorgabewert
|-
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden? (auch bei ''null'')
|-
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste
|-
| <code>oReader.IsArr('zeiten')</code> / <code>IsObj('zeiten[0]')</code> || Gestalt prüfen
|-
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst
|}

'''Verschachtelung steht im Pfad''' - Punkt für Felder, eckige Klammern für Listen:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cVon : string;
nAnz : Integer;
nI : Integer;
begin
nAnz := oReader.Count('zeiten');
for nI := 0 to nAnz - 1 do begin
if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
// ... cVon verarbeiten ...
end;
end;
end;
</syntaxhighlight>

{{Hinweis|'''Der Rückgabewert unterscheidet „nicht gesendet" von „leer
gesendet".''' <code>oReader.Str('feld', cWert)</code> liefert bei
<code>"feld": null</code> ''true'' mit leerem Wert und bei fehlendem Feld
''false''. Genau diese Unterscheidung braucht ein PATCH-artiger Aufruf: „Feld
löschen" und „Feld nicht anfassen" sehen sonst gleich aus.}}

Ist gar kein Körper gesendet worden, liefert jeder Leser ''false'' und
''HasBody()'' ist ''false''. Maximale Body-Grösse: 10 MB - bei einem gepackt gesendeten Körper zusätzlich das 400fache der gesendeten Grösse, siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression. Beide Überschreitungen beantwortet der Server mit '''413''', das Skript läuft gar nicht erst an.

===Werte des Servers===

Bei aktiver JWT-Authentifizierung stehen die Token-Claims über den Reader zur
Verfügung. Sie tragen intern weiterhin die Namen mit Präfix '''_OBS_''' - im
Skript werden sie aber über die Zugriffe der Tabelle oben gelesen und nicht mehr
über den Namen:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_JWT_ID')</code> || JWT-Id (''jti''-Claim) - typisch die User-Id. '''Muss nicht eindeutig sein''': die Sitzung führt der Server über eigene Kennungen (siehe unten)
|-
| <code>oReader.Subject()</code> || Subject (''sub''-Claim) - typisch Benutzername
|-
| <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> || Audience (''aud''-Claim) - typisch Mandant / Rolle
|-
| <code>oReader.Claim('tenant')</code> || Beliebiger Custom-Claim des Tokens, hier ''tenant''; im Folge-Skript lesbar
|-
| <code>oReader.TraceId()</code> || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}

Unabhängig von JWT stehen ausserdem immer zur Verfügung:

{| class="wikitable"
! Parameter !! Inhalt
|-
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Aktuelle Serverzeit als ISO-8601 '''mit UTC-Offset''' (z.B. ''2026-08-17T09:12:33+02:00''). Nützlich, um Datumswerte in derselben Zeitzone auszuliefern, in der der Server arbeitet, und damit ein Client seinen Uhren-Versatz bestimmen kann
|-
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+02:00''. Er geht in die Zeitfunktionen (siehe [[#Zeitangaben auf der Leitung|Zeitangaben]])
|-
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden (''JWT-Exp'' × 60). Damit kann ein Konfigurations-Endpunkt denselben Wert ausliefern, den der Token wirklich hat
|}

Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.

Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
''oReader.Claim('sid')'' und ''oReader.Claim('rid')'':

{| class="wikitable"
! Claim !! Inhalt
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
|}

Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Skripts gesetzt - ein Skript kann sie also auch mit einem eigenen Claim ''sid''
nicht überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.

===Pfad-Parameter===

Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte über ''oReader.Path'' bereit:

{| class="wikitable"
! Template !! Zugriff im Skript
|-
| <code>/orders/{uid}</code> || <code>oReader.Path('uid')</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>oReader.Path('uid')</code>, <code>oReader.Path('code')</code>
|}

Diese Werte kommen aus dem Routing und sind durch den Client nicht fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].

===Datei-Uploads===

Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), nimmt der Server
hochgeladene Dateien entgegen, legt sie in einem temporären Verzeichnis ab und
übergibt dem Skript Pfad, Originalname und Content-Type über den Reader. Das
Skript entscheidet selbst über die weitere Verarbeitung (z.B. DMS-Ablage). Der
Body wird in diesem Fall '''nicht''' als JSON geparst - ''oReader.HasBody()'' ist
''false''. Es gilt nicht das JSON-Body-Limit (10 MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25 MB;
Überschreitung -> 413).

'''Wie die Datei übertragen wurde, spielt für das Skript keine Rolle.''' Beide
Wege - <code>multipart/form-data</code> und der resumable
<code>Content-Range</code>-Upload - liefern dieselben vier Werte. Das
Übertragungsprotokoll samt Header, Statuscodes und Resume-Verhalten steht in
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]:

{| class="wikitable"
! Aufruf !! Inhalt
|-
| <code>oReader.UploadPath()</code> || Vollständiger Pfad zur temporären Datei auf dem Server
|-
| <code>oReader.UploadName()</code> || Originaldateiname
|-
| <code>oReader.UploadType()</code> || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt), kleingeschrieben
|-
| <code>oReader.UploadSha()</code> || SHA-256 der '''gespeicherten''' Datei, hex in Kleinbuchstaben. Damit lässt sich eine vom Client mitgesendete Prüfsumme vergleichen - erst dieser Vergleich macht aus ihr eine Zusicherung
|}

Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''UploadPath()'' und ''UploadName()'' gefüllt
sind, sobald es läuft.

{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}

Zusatzangaben, die im selben Aufruf mitkommen, liest das Skript mit
<code>oReader.Form('<name>')</code> - bei <code>multipart/form-data</code> sind
das die Partien ohne <code>filename=</code>. Ein vollständiges Beispiel zeigt
[[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].

==Die Antwort schreiben: oWriter==

Der Writer schreibt '''sequentiell''': jeder Aufruf hängt ein Feld an, an der
Stelle, an der er steht. Die äussere Klammer der Antwort setzt der Server. Wird
nichts geschrieben, antwortet er mit ''{}''. Content-Type ist
''application/json; charset=utf-8'', der Status 200, sofern das Skript nichts
anderes setzt.

Einfaches Beispiel:

<syntaxhighlight lang="pascal" line>
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
oWriter.Str('wert_string', '123');
oWriter.Int('wert_int' , 456);
end;
</syntaxhighlight>

{| class="wikitable"
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
| <code>oWriter.StrN('name', cWert)</code> || wie ''Str'', aber '''null''' statt einer leeren Zeichenkette
|-
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. '''Immer mit Dezimalpunkt''', unabhängig von der Locale des Servers
|-
| <code>oWriter.Bool('aktiv', lWert)</code> || ''true'' / ''false''
|-
| <code>oWriter.Null('lat')</code> || ausdrücklich ''null''
|-
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
| <code>oWriter.RootArr()</code> || Die '''Wurzel''' ist eine Liste statt eines Objekts. Muss vor dem ersten Feld stehen; ein ''ArrEnd'' gibt es dazu nicht
|-
| <code>oWriter.Raw('meta', cJson')</code> || Fertiges JSON-Fragment einbetten. Siehe unten
|}

'''In einer Liste hat ein Eintrag keinen Namen''' - der leere Feldname ist genau
das:

<syntaxhighlight lang="pascal" line>
oWriter.ArrBegin('dateien');
while (not q.EoF) do begin
oWriter.ObjBegin('');
oWriter.Str ('uid' , q.A2C('f_uid'));
oWriter.Int ('bytes' , q.A2I('f_bytes'));
oWriter.StrN('kategorie', AllTrim(q.A2C('f_kat'))); // null wenn leer
oWriter.ObjEnd;
q.Next();
end;
oWriter.ArrEnd;
</syntaxhighlight>

Ein Name in einer Liste und ein fehlender Name in einem Objekt sind beides
'''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die
Stelle im Protokoll - er liefert kein halbes JSON aus. Dasselbe gilt für einen
Stapel, der am Ende der Methode noch offen ist.

{{Hinweis|'''Ein Helfer bekommt den Writer als Parameter''' und schreibt an der
Stelle hinein, an der er aufgerufen wird - er gibt kein Fragment zurück. Damit
steht die Reihenfolge der Antwort im Code und nicht im Zusammenbau:

<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}

'''Raw ist der Notausgang und prüft.''' Er parst das Fragment und bettet den
'''Originaltext''' ein; ungültiges JSON gibt einen Serverfehler, der das Feld
nennt. Gebraucht wird er für ein gespeichertes, '''signiertes''' Dokument:
Parsen und Neuserialisieren würde die signierte Feldreihenfolge zerstören.

===Zeitangaben auf der Leitung===

Zeitstempel gehen als '''ISO-8601 mit Offset''' über die Leitung. Die Wandlung
gehört nicht ins Skript - dort saß der Fehler „zwei Stunden zu früh" an drei
Stellen gleichzeitig:

{| class="wikitable"
! Aufruf !! Zweck
|-
| <code>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt -> ''2026-09-09T14:12:00+02:00''. Leerer String bei leerem Datum
|-
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette -> OBS-Zeitpunkt in '''Ortszeit des Servers'''
|-
| <code>oReader.Offset()</code> || Der Offset, der in beide hineingeht
|-
| <code>RestOffsetToMinutes(cOffset)</code> || Offset in Minuten, für eigene Rechnungen
|}

==Antwort steuern: Statuscode, Header, traceId==

Statuscode, Header und das Sperren einer Sitzung laufen über eigene Aufrufe des
Writers, '''nicht''' über Felder im Körper.

{| class="wikitable"
! Aufruf !! Wirkung
|-
| <code>oWriter.Status(201)</code> || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200
|-
| <code>oWriter.Header('ETag', '7')</code> || Beliebiger Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen und Werten werden entfernt (Schutz vor Header-Injection)
|-
| <code>oWriter.NoBody()</code> || Kein Körper - für '''204'''
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens (''session'') oder alle Sitzungen des Subjects (''all''). Damit wird ein Endpunkt zum Logout, ohne eigene Verwaltung. Scheitert das Sperren, antwortet der Server mit '''503''' statt mit der Antwort des Skripts - siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Abschnitt Abmelden
|-
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld „menge" fehlt')</code> || Fertige Fehlerantwort in der Form des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer? Für einen Verteiler, der danach noch etwas anhängen will
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Statt eines JSON-Körpers eine '''Datei''' ausliefern. Die Datei bleibt liegen, der Download ist wiederaufsetzbar. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Wie <code>SendFile</code>, aber die Datei wird nach dem Senden '''gelöscht''' und der Download ist nicht wiederaufsetzbar - für Ergebnisse, die je Abruf entstehen (CSV-Export, Report)
|}

Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oReader.TraceId()'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.

Setzt ein Skript den Header '''Content-Encoding''' selbst - etwa weil es einen bereits gepackten Körper ausliefert -, hält sich die Engine heraus und packt die Antwort nicht noch einmal. Ohne diesen Header entscheidet der Server selbst, ob gzip zum Einsatz kommt.

===Beispiel: Anlegen mit 201, Location und ETag===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueUid: string;
begin
// ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...

oWriter.Str('uid', cNeueUid);
oWriter.Status(201);
oWriter.Header('Location', '/v1/orders/' + cNeueUid);
oWriter.Header('ETag' , '1');
end;
</syntaxhighlight>

===Beispiel: Strukturierter Fehler mit Statuscode und traceId===

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var nMenge: Integer;
begin
if (not oReader.Int('menge', nMenge)) then begin
// Statuscode, code, message, uid und traceId in EINEM Aufruf - dieselbe
// Huelle, die auch die Server-eigenen Fehler tragen.
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

===Beispiel: Optimistic Concurrency (ETag / If-Match)===

Mit Statuscode, Headern und dem lesbaren Header ''If-Match'' führt das Skript je Datensatz einen Versionszähler und lehnt veraltete Schreibzugriffe mit 409 ab:

<syntaxhighlight lang="pascal" line>
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
nIfMatch: Integer;
begin
nAktuell := AuftragVersion(oReader.Path('uid'));
nIfMatch := iVal(oReader.Param('if-match'));

if (nIfMatch <> nAktuell) then begin
// Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
// gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
oWriter.Header('ETag', xStr(nAktuell));
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geaendert');
exit;
end;

// ... speichern, Version hochzählen ...
oWriter.Header('ETag', xStr(nAktuell + 1));
end;
</syntaxhighlight>

==Idempotenz - was das Skript beachten muss==

Bei ''POST''/''PUT''/''PATCH''/''DELETE'' fängt der '''Server''' doppelte
Sendungen über den Header <code>Idempotency-Key</code> ab. Das Skript braucht dafür
'''keine eigene Logik''' - keine Schlüssel-Tabelle, keine Prüfung am Anfang der
Methode.

{{Hinweis|Der Header ist bei diesen vier Verben '''Pflicht'''. Fehlt er, antwortet
der Server mit '''400''' <code>IDEMPOTENCY_KEY_MISSING</code> - das Skript läuft
dann gar nicht erst an, es muss den Fall also auch nicht behandeln.}}

Was das Skript wissen muss:

{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
|-
| '''2xx''' || Statuscode, Body und Header werden gespeichert. Eine Wiederholung mit demselben Schlüssel bekommt genau diese Antwort zurück, das Skript läuft nicht erneut
|-
| '''2xx''' mit ''SendFile''/''SendTempFile'' || '''Nichts''' wird gespeichert - eine Dateiantwort liesse sich nicht wiedergeben. Der Schlüssel wird freigegeben und ist danach wieder benutzbar
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
|-
| '''5xx''' oder Exception || Der Schlüssel wird ebenfalls '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden
|}

{{Achtung|'''Das 5xx-Verhalten wurde am 25.08.2026 gedreht.''' Vorher blieb der
Schlüssel nach einem Serverfehler belegt - begründet mit „niemals eine
Doppelbuchung". Das war falsch gewichtet: der Vorgang wurde damit
'''unwiederholbar''', der Client bekam dauerhaft 503 und hätte die erfasste Arbeit
verwerfen müssen. Garantierter Datenverlust wiegt schwerer als ein möglicher
Doppelsatz.

'''Folge für die Auslegung:''' Ein schreibender Endpunkt sollte selbst
wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines
Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.}}

Daraus folgen zwei Regeln für Endpunkt-Skripte:

* '''Fachliche Ablehnungen als 4xx melden''' (422, 409, 404), nicht als 2xx mit Fehlertext im Body. Sonst wird die Ablehnung gespeichert und der Konsument bekommt sie bei jedem weiteren Versuch erneut - auch nachdem er den Fehler behoben hat.
* '''Die Antwort muss vollständig sein.''' Was zurückgegeben wird, wird eingefroren. Ein Feld, das erst der zweite Aufruf ergänzen würde, kommt beim Konsumenten nie an.

Der vollständige Ablauf und die Statuscodes stehen unter
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].

==JWT-Authentifizierungs-Skript==

Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:

<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
// Eingangsdaten lesen
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);

// Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
if (PasswortPasst(cUser, cPass)) then begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_AUDIENCE', 'mandant1');
end else begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;
</syntaxhighlight>

{{Hinweis|'''Im Anmeldeskript bleiben die _OBS_JWT_*-Felder Felder der
Antwort''' - anders als Status und Header, die zu Aufrufen des Writers geworden
sind. Der Grund: die Token-Ausstellung liest sie aus dem fertigen Körper, und
genau dort erwartet sie sie. Geschrieben werden sie deshalb wie jedes andere
Feld, nur eben mit dem Writer.}}

Rückgabewerte:

{| class="wikitable"
! status !! Bedeutung
|-
| 1 || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
|-
| 9 || Misserfolg, der Server antwortet mit '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
|}

{{Hinweis|Der Text aus ''error'' geht bei ''status'' = 9 '''an den Konsumenten'''
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Endanwender verständlich sein und keine internen Details verraten.}}

Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
„Passwort falsch" erscheinen.

Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.

===Aufbau der Token-Antwort===

Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
Feldern, die das Skript zurückgibt''':

{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
"token": "eyJ...",
"accessToken": "eyJ...",
"refreshToken":"eyJ...",
"expiresIn": 28800,
"serverTime": "2026-08-17T09:12:33+02:00"}

{| class="wikitable"
! Feld !! Herkunft
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
|-
| serverTime || Serverzeit ISO-8601 mit Offset
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
|}

Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.

===Custom-Claims, serverTime und Refresh===

Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:

{| class="wikitable"
! RÜckgabefeld !! Bedeutung
|-
| _OBS_JWT_CLAIM_<name> || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als <code>oReader.Claim('<name>')</code>.
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
|}

Jedes Token trägt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh'') sowie die Sitzungskennungen ''sid'' und ''rid'' des Servers. Die Antwort enthält bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusätzlich ''refreshToken'':

{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}

{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''oReader.Claim(…)''), nie aus Body oder Query.}}

====Refresh-Methode====

Der Refresh läuft über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' mit einem Refresh-Token vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (ohne Bearer: Login; ''DELETE'' mit Access-Token: Abmelden, ohne Skript).

Bevor das Skript läuft, hat der Server das vorgelegte Refresh-Token verifiziert
(Signatur, Ablauf, ''token_use=refresh'') und in der Sitzung '''entwertet'''.
Einmalgebrauch, Rotation und Sperrliste sind damit Sache des Servers. Das Skript
liefert nur noch die aktuellen Claims - genau das ist der Sinn des Aufrufs: eine
zwischenzeitlich geänderte Rolle oder ein gewechselter Mandant wirken spätestens
mit der nächsten Erneuerung.

{{Achtung|Eine '''eigene Sperrtabelle im Skript ist nicht mehr nötig''' und sollte
entfernt werden. Wer sie weiterführt, rotiert zweimal - einmal im Skript, einmal im
Server - und riskiert, dass beide Seiten unterschiedlicher Meinung sind. Der
Server sieht die Skript-Tabelle nicht, und das Skript sieht die Sitzung nicht.}}

Ein bereits benutztes Refresh-Token wird mit '''401''' abgelehnt. Erfolgt die
erneute Vorlage innerhalb von 60 Sekunden, bleibt die Sitzung bestehen (paralleler
Refresh einer App); danach gilt sie als Wiedervorlage und die '''gesamte Sitzung
wird gesperrt'''. Details in [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].

Das alte Refresh-jti steht weiterhin als ''oReader.Param('_OBS_JWT_ID')'' bereit,
falls das Skript es für eigene Protokollierung braucht.

<syntaxhighlight lang="pascal" line>
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();

// Der Server hat das vorgelegte Refresh-Token bereits geprueft und
// entwertet. Hier wird nur entschieden, ob der Benutzer die Sitzung
// fortsetzen darf - und mit welchen Rechten.
if (not BenutzerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
exit;
end;

// Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
// sonst wirkt ein Rechteentzug erst beim naechsten Login.
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // loest das neue Refresh-Token aus
end;
</syntaxhighlight>

===Abmelden (Logout)===

'''Für das Abmelden braucht das Skript keine Methode.''' Es läuft über ein
''DELETE'' auf denselben JWT-Endpunkt (Access-Token im ''Authorization''-Header)
und wird komplett in der Engine erledigt: die Sitzung wird gesperrt, die Antwort
ist 204. Eine Methode ''Logout'' gibt es nicht und wird nicht aufgerufen.
Details: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]], Phase 4.

Wer beim Abmelden zusätzlich fachlich etwas tun will - eine Geräteregistrierung
löschen, einen Push-Token verwerfen, den Vorgang protokollieren - nimmt einen
'''gewöhnlichen Endpunkt''' und ruft dort ''oWriter.JwtRevoke''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
GeraeteRegistrierungLoeschen(oReader.Subject());

// 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
oWriter.JwtRevoke('session');
oWriter.Status(204);
oWriter.NoBody();
end;
</syntaxhighlight>

Gesperrt wird in beiden Wegen die '''ganze Sitzung''', also auch die noch nicht
abgelaufenen Access-Token vorheriger Erneuerungen. Ein wiederholter Aufruf ist
unschädlich. Lässt sich die Sitzung nicht sperren, überschreibt der Server die
Antwort des Skripts mit '''503''' - ein Client darf nicht glauben, er sei
abgemeldet, während sein Token weiterläuft.

==Fehlerbehandlung im Skript==

Tritt im Skript eine Exception auf oder schlägt die Syntax-Prüfung fehl, antwortet der Server mit 500 ''Interner Fehler'' und protokolliert die Detail-Meldung in '''RESTSRV_PROTO''' (mit Skript-Fehlertext). Der Konsument sieht keine internen Details.

Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Für einen spezifischen Fehler an den Konsumenten gibt es '''einen''' Aufruf. Er
baut dieselbe Hülle, die auch die Server-eigenen Fehler tragen - Statuscode,
''code'', ''message'', ''uid'' und ''traceId'' -, sodass beide Wege nicht
auseinanderlaufen können:

<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
begin
if (Empty(oReader.Param('kundennr'))) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
exit;
end;
// ...
end;
</syntaxhighlight>

{{Hinweis|'''Error verwirft einen schon begonnenen Körper''' und setzt seinen
eigenen. Ein Skript darf also getrost Felder schreiben und danach noch
abbrechen - was der Client sieht, ist die Fehlerantwort. Nur ein '''offener
Stapel''' (ein ''ObjBegin'' ohne ''ObjEnd'') bleibt auch dann ein Strukturfehler.}}

{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
Body auszuwerten - und nur so gibt der Server einen belegten
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}

===Ändern: qSqlInit statt qSqlRead===

Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
benutzt - der Satz wird über <code>sys_uid</code> adressiert:

<syntaxhighlight lang="pascal" line>
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cSysUid); // Schreib-Index auf den Originalsatz
q.qSet('ti_status', '9');
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln, siehe unten
end;
qSqlFree(q);
</syntaxhighlight>

<code>qSqlRead</code> ist dafür die falsche Wahl, aus zwei Gründen:

* Es liest den '''kompletten Altsatz''' ein - ein zusätzlicher Lesezugriff, der Zeit kostet.
* Es schreibt anschliessend nur die '''Änderungen'''. Ist der neue Wert gleich dem alten, entsteht gar kein Write, und <code>SaveData</code> liefert '''False''' - ununterscheidbar von einem echten Fehlschlag.

{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen'''
Datensatz an, statt den vorhandenen zu ändern. Die <code>sys_uid</code> ist der
Schreib-Index und gehört bei jeder Änderung gesetzt.}}

Damit entfällt auch das übliche Paar aus <code>DB_LSeek</code> und
<code>qSqlRead</code>: '''eine''' Abfrage auf die <code>sys_uid</code> liefert
zugleich die Existenzprüfung und den Schreib-Index.

<syntaxhighlight lang="pascal" line>
cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM tickets WHERE ' + cWhere + ' LIMIT 1', q)) then begin
if (not q.EoF) then begin
cUid := q.A2UID();
end;
end;
DB_Close(q);

if (not Empty(cUid)) then begin
// ändern: qSqlInit + sys_uid
end else begin
// anlegen: qSqlInit ohne sys_uid
end;
</syntaxhighlight>

===Mehrere Felder sind EIN Schreibvorgang===

Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:

<syntaxhighlight lang="pascal" line>
// FALSCH: fünf Felder, fünf Schreibvorgänge - und jeder Setzer, der sich
// seine sys_uid selbst holt, bringt zusätzlich eine eigene Abfrage mit
FeldSetzen(cUid, 'ti_status' , '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von' , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
q.qSet('sys_uid' , cUid);
q.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
q.qSet('ti_von' , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
// ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>

Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
sind '''nicht atomar'''. Bricht der dritte Schreibvorgang ab, steht die Zeile
halb geändert da - Grund gesetzt, Zeitpunkt nicht.

Wird nichts gesetzt, darf auch nicht geschrieben werden: das Schreibobjekt dann
mit <code>qSqlFree</code> freigeben, statt ein leeres <code>SaveData</code>
abzusetzen.

{{Hinweis|Ein Setzer für '''ein''' Feld (<code>FeldSetzen(cUid, cFeld, cWert)</code>)
ist bequem und deshalb verführerisch. Er versteckt aber je Aufruf eine eigene
Abfrage und ein eigenes <code>SaveData</code>. Für einen Vorgang mit mehreren
Feldern gehört ein '''Editier-Helfer''' her, der das Schreibobjekt liefert -
geschrieben wird einmal am Ende.}}

===Keine Abfrage je Zeile===

Was in einer Liste je Zeile nachgeschlagen wird, kostet '''N''' Abfragen für
'''eine''' Antwort. Bei fünfzig Aufträgen sind das fünfzig Abfragen für ein
einziges Feld. Der Ausweg ist immer derselbe:

* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen - bei einem '''eindeutigen''' Index auf dem Join-Feld kann er die Zeilen nicht vervielfachen.
* Einzelwerte aus einer 1:n-Beziehung über eine '''Unterabfrage''' in der SELECT-Liste holen, nicht über einen Join (der Join würde die Zeilen vervielfachen).
* Eine echte Unterliste (Positionen, Dateien) nur dann nachladen, wenn ein '''Zählfeld''' in der Hauptabfrage sagt, dass es überhaupt eine gibt.

{{Hinweis|Ein GET soll '''lesen'''. Schreibvorgänge im Lesepfad - etwas
"beim ersten Ausliefern festschreiben" - vervielfachen sich mit der Zeilenzahl
und treffen den Aufrufer, der nur eine Liste angefordert hat.}}

===Schreibfehler erkennen===

'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
Fehlermeldung, die es gibt.''' (Auch der '''Parameter''' ist ein Boolean:
''NEW_RECORD'' und ''UPDATE_RECORD'' sind Wahrheitswerte, keine Zahlen.) Schlägt das Schreiben in der Datenbank fehl
(''Duplicate entry'' auf einem eindeutigen Index, zu langer Wert, fehlende
Spalte), dann

* wird '''keine''' Exception ausgelöst,
* steht '''nichts''' in ''RESTSRV_PROTO'',
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.

Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Weil in einem Endpunkt schnell ein Dutzend Schreibvorgänge zusammenkommen, gehört
die Prüfung in eine eigene kleine Prozedur - am besten in die gemeinsame Lib:

<syntaxhighlight lang="pascal" line>
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
lOk := q.SaveData(lNeu);
qSqlFree(q); // auch im Fehlerfall freigeben
if (not lOk) then begin
raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
end;
end;

// Aufruf statt SaveData + qSqlFree:
q := qSqlInit(oDB, 'tickets');
q.qSet('ti_betreff', cBetreff);
Speichern(q, NEW_RECORD, 'Ticket');
</syntaxhighlight>

Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
nach '''RESTSRV_PROTO''' und antwortet mit '''500'''. Liegt ein
''Idempotency-Key'' an, wird er dabei '''freigegeben''' - die Anfrage ist also
wiederholbar (siehe Abschnitt Idempotenz).

{{Hinweis|Ein fehlgeschlagenes Schreiben ist kein Fall, in dem ein Endpunkt
sinnvoll weiterlaufen kann: die Fachwirkung ist dann unvollständig. Wer trotzdem
weitermachen will - etwa weil mehrere unabhängige Sätze geschrieben werden -,
prüft den Rückgabewert und baut selbst eine Antwort. Ignorieren darf man ihn
nie.}}

Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.

==Gemeinsamen Code auslagern==

Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:

<pre>
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</pre>

{| class="wikitable"
! Attribut !! Bedeutung
|-
| '''T''' || Tabelle, aus der geladen wird
|-
| '''I''' || Spalte, über die gesucht wird
|-
| '''V''' || Wert, der in dieser Spalte stehen muss
|-
| '''F''' || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}

Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Compiler sieht danach den zusammengesetzten Text - eine Funktion aus der Lib lässt
sich also aufrufen wie eine im Skript selbst geschriebene.

===Bewährtes Muster: Lib als eigene Endpunkt-Zeile===

Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
RESTSRV_ENDPOINTS''' abzulegen:

# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
# Den Lib-Quelltext ins Skript-Feld dieser Zeile schreiben (F7).
# '''Keine Berechtigung''' in der Berechtigungs-Liste vergeben - das ist der Schutz: ohne Berechtigung beantwortet der Server einen Aufruf mit 403.
# In jedem nutzenden Endpunkt die Direktive oben einfügen.

Damit ist die Lib reiner Ablageort und von aussen nicht nutzbar. Eine Änderung
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
angefasst werden muss.

{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Funktion hinzu, genügt es nicht, nur das nutzende Skript zu aktualisieren. Eine
ältere Lib lädt fehlerfrei - der Compiler meldet dann ausschliesslich die neuen
Namen als ''Unknown name'', was leicht wie ein Fehler im Skript aussieht.}}

{{Hinweis|Auch hier greift der Endpunkt-Cache: eine Änderung an der Lib wird erst
nach Ablauf des TTL (bis zu 60 Sekunden) wirksam.}}

===Wohin gehört welcher Code?===

Drei Ebenen, und die Zuordnung entscheidet, wie schnell eine Änderung wirkt:

{| class="wikitable"
! Art des Codes !! Wohin !! Wirksam
|-
| Fachlogik **einer** Anwendung - Feldnamen, Zustandswerte, Rollenregeln, Schreibziele || in die '''DWS-Lib dieser Anwendung''' (eigene Endpunkt-Zeile, per <code>{$L …}</code> eingebunden) || nach Ablauf des Cache-TTL, ohne Build
|-
| Mechanik, die '''mehrere''' Anwendungen brauchen - und auch das OBS-Umfeld || nach '''obs_lib''' als Delphi-Unit || erst nach Build und Rollout
|-
| Mechanik, die '''nur''' der REST-Server braucht || in die Units des Servers || erst nach Build und Rollout
|}

Die Regel hat einen praktischen Grund und keinen ästhetischen: Fachlogik ändert
sich in Tagen, Mechanik in Monaten. Was in der Lib liegt, ist nach einer Minute
aktiv; was in einer Unit liegt, braucht einen Build. Wer Fachlogik nach unten
schiebt, tauscht Geschwindigkeit gegen nichts ein.

{{Hinweis|Eine Anwendung, die ihre eigene Lib hat, kopiert sie '''nicht''' von
einer anderen. Zwei Kopien derselben Lib driften auseinander, und die Abweichung
fällt erst auf, wenn eine der beiden Anwendungen etwas Falsches tut. Geteiltes
gehört eine Ebene tiefer.}}

==Fallstricke im Skript==

Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:

{| class="wikitable"
! Stolperstein !! Richtig
|-
| ''DB_SOpen('Y00…', oDB, …)'' - der AD-UID-Parameter aus dem Delphi-Code || Im Skript '''ohne UID''': <code>DB_SOpen(oDB, cSql, q)</code>. Gleiches gilt für <code>qSqlInit(oDB, 'tab')</code> und <code>qSqlRead(oDB, 'tab', cWhere)</code> - jede dieser Funktionen beginnt mit ''oDB''
|-
| ''oReader.Str<T>(…)'' oder irgendein Generic || Generics gibt es in der Skriptsprache nicht. Die Leser sind je Typ eigene Methoden: ''Str'', ''Int'', ''Num'', ''Bool''
|-
| Eine eigene Prozedur ''Delete'' für DELETE || ''Delete'' ist eine '''Standardprozedur''' der Sprache. Die Deklaration lässt sich nicht übersetzen, und die Meldung nennt nur die Zeile - nicht die Ursache
|-
| Ein Helfer, der ein JSON-Fragment als String zurückgibt || Den '''Writer als Parameter''' übergeben und an der richtigen Stelle hineinschreiben. Fragmente von Hand zusammenzusetzen ist genau der Weg, auf dem die Reihenfolge und die Klammern verloren gingen
|-
| ''oWriter.ArrEnd'' nach ''RootArr'' || ''RootArr'' öffnet '''keine''' Ebene, es bestimmt nur die Klammer der Wurzel. Ein ''ArrEnd'' dazu ist ein Strukturfehler
|-
| Zahlen selbst formatieren (''NStr'', ''StrTran'') || <code>oWriter.Num('preis', nWert, 2)</code>. Selbst formatiert stand bei Werten ab 1000 der Tausendertrenner im JSON - gültiges JSON, falscher Wert, keine Meldung
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'|' + wert + '|'</code>) und mit ''Pos'' prüfen
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
|-
| <code>q.SaveData(…)</code> als Anweisung schreiben || ''SaveData'' liefert einen '''Boolean'''. Ein SQL-Fehler beim Schreiben wirft '''keine''' Exception und landet in '''keinem''' Protokoll - der Rückgabewert ist die einzige Meldung. Immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Setzer-Aufruf || Ein <code>qSqlInit</code>-Objekt, beliebig viele <code>qSet</code>, '''ein''' <code>SaveData</code>. Einzeln geschrieben kostet jedes Feld eine eigene Abfrage samt eigenem Write - und der Vorgang ist nicht mehr atomar, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || In einer Liste sind das N Abfragen für eine Antwort. Über <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n) mitnehmen, siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skript-VM zum '''Absturz''' (Assertion in ''dwsStack.pas''), und zwar beim ersten '''Lesen''' des Werts - nicht schon beim Schreiben, die Ursache liegt also nicht dort, wo der Fehler auffällt. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und erst beim Aufrufer wandeln
|}

==Skript-Cache==

Der Server cached das kompilierte Skript pro Endpunkt (Schlüssel: ''sys_date'' des Endpunkts). Zusätzlich werden die Endpunkt-Definitionen pro Server-Profil in einem TTL-Cache (Standard 60 s) gehalten. Eine Skript-Änderung über F7 wird daher erst nach Ablauf dieses TTL (bzw. nach einer Cache-Invalidierung) wirksam - typischerweise innerhalb einer Minute, nicht zwingend sofort.

==Verfügbare Bibliotheken==

Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:

* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
* ''Base.qSqlReg'' - Schreibzugriffe
* ''lib_ScriptIO'' - Writer und Reader, siehe unten. '''System.JSON braucht ein Endpunkt-Skript nicht''' - der Writer erzeugt die Antwort, der Reader liest den Körper
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''
* ''lib_ScriptIO'' - ''TxRestWriter'', ''TxRestReader'' und die Zeitfunktionen ''RestIsoFromDate'' / ''RestDateFromIso'' / ''RestOffsetToMinutes''. Writer und Reader bekommt das Skript als Parameter; die Zeitfunktionen ruft es direkt

Die wichtigsten Aufrufe mit ihren Skript-Signaturen:

{| class="wikitable"
! Zweck !! Aufruf
|-
| Lesen || <code>DB_SOpen(oDB, cSql, q)</code>, dann <code>q.EoF</code>, <code>q.Next()</code>, <code>q.A2C('feld')</code> / <code>A2I</code> / <code>A2F</code> / <code>A2D</code> / <code>A2UID()</code>, am Ende <code>DB_Close(q)</code>
|-
| Neu anlegen || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('feld', wert)</code>, <code>if (not q.SaveData(NEW_RECORD)) then …</code>, <code>qSqlFree(q)</code> – der Rückgabewert ist Pflicht, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Ändern || <code>q := qSqlInit(oDB, 'tab')</code>, <code>q.qSet('sys_uid', cUid)</code>, <code>q.qSet(…)</code>, <code>if (not q.SaveData(UPDATE_RECORD)) then …</code>, <code>qSqlFree(q)</code> – '''nicht''' <code>qSqlRead</code>, siehe [[#Ändern: qSqlInit statt qSqlRead|Ändern]]. Alle Felder derselben Zeile in '''ein''' Objekt, siehe [[#Mehrere Felder sind EIN Schreibvorgang|Mehrere Felder]]
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
|-
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
|}

{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
Skript nicht übersetzen.}}

Konkrete Beispiele:

* [[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]]

OBS/Kostenpflichtige Module/RESTServer/Endpunkte

2026-09-25T09:28:32Z

MINERVA-Rademacker: Idempotency-Key als Pflicht, Aufraeumen offener Reservierungen berichtigt, Fehlercodes 400/503/308 ergaenzt [Volltext ersetzt]

{{Kostenpflichtige Module}}

= Endpunkte =

Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
realisiert und ist genau einem Server-Profil zugeordnet.

== Routing über Pfad-Templates ==

Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
'''Platzhalter''' enthalten:

* '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
* '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.

Beispiele für gültige Templates:

{| class="wikitable"
! Template !! Passt auf !! Pfad-Parameter
|-
| <code>/orders</code> || <code>/orders</code> || –
|-
| <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
|-
| <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
|-
| <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
|}

=== Präzedenz bei mehreren Treffern ===

Passen mehrere Templates auf denselben Pfad, '''gewinnt das spezifischste''' –
also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code>
das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf
<code>/orders/{uid}</code> matcht.

== Hauptfelder eines Endpunkts ==

{| class="wikitable"
! Feld !! Spalte !! Zweck
|-
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
|-
| '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
|-
| '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
|-
| '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
|-
| '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
|-
| '''Info''' || – || Dokumentations-Freitext
|-
| '''Datei-Upload''' || <code>re_upload</code> || Erlaubt Datei-Uploads an diesem Endpunkt (<code>0</code> = aus, <code>1</code> = an). Ohne Freigabe werden Upload-Anfragen mit 415 abgelehnt.
|-
| '''Max. Upload-Grösse''' || <code>re_upload_size</code> || Maximale Dateigrösse in MB. Leer/0 = Standard 25 MB. Überschreitung wird mit 413 abgelehnt.
|}

== Pfad-Parameter im Skript ==

Die aus den Platzhaltern erfassten Werte liest das Endpunkt-Skript über
<code>oReader.Path</code>:

<syntaxhighlight lang="pascal">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
cUid := oReader.Path('uid'); // aus /orders/{uid}
// ...
end;
</syntaxhighlight>

Diese Werte stammen aus dem Routing und können nicht durch den Client
überschrieben werden.

== Datei-Uploads ==

Ein Endpunkt nimmt Datei-Uploads nur entgegen, wenn er dafür freigeschaltet ist
(<code>re_upload = 1</code>). Andernfalls werden Upload-Anfragen mit
'''415 Unsupported Media Type''' abgelehnt und das Skript wird nicht ausgeführt.

Die maximal zulässige Dateigrösse wird pro Endpunkt über <code>re_upload_size</code>
(in MB) festgelegt; ohne Angabe gilt der Standard von '''25 MB'''. Wird das
Limit überschritten, antwortet der Server mit '''413 Payload Too Large'''. Für
Uploads gilt nicht das JSON-Body-Limit (10 MB), sondern dieses Endpunkt-Limit.
Der Originalname (beim resumable Upload über den Header <code>Upload-Metadata</code>) ist '''Pflicht'''; fehlt er, wird der Upload mit '''400''' abgelehnt, ohne dass eine Datei angelegt wird. Das Skript liest Pfad, Name, Content-Type und die SHA-256-Prüfsumme der gespeicherten Datei über <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code> und <code>UploadSha()</code>; bei <code>multipart/form-data</code> die übrigen Formularfelder über <code>oReader.Form('<name>')</code>.

'''Das Übertragungsprotokoll''' - Header, Statuscodes, Resume-Verhalten - steht auf einer eigenen Seite: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]].

Unterstützt werden zwei Übertragungsarten:

* '''Einfacher Upload''' per <code>multipart/form-data</code> (eine Datei pro Request).
* '''Resumable/Chunked Upload''' per <code>Content-Range</code> (grosse Dateien, fortsetzbar nach Abbruch).

Der Server legt die hochgeladene Datei in einem temporären Verzeichnis ab und
übergibt dem Endpunkt-Skript den Pfad. Was mit der Datei geschieht (Ablage,
DMS-Verknüpfung, Weiterverarbeitung), entscheidet allein das Skript. Details und
Beispiele: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Datei-Downloads ==

Ein Endpunkt kann eine '''Datei''' statt eines JSON-Körpers zurückgeben -
PDF, CSV, eine APK. Dafür ist '''keine Freischaltung''' nötig: ein Download
entsteht dadurch, dass das Skript ihn mit <code>oWriter.SendFile(...)</code>
bzw. <code>oWriter.SendTempFile(...)</code> erzeugt, nicht dadurch, dass ein
Client ihn anfragt.

Content-Type, Dateiname, Bereichsanfragen (<code>Range</code>, '''206'''),
ETag und das Aufräumen temporärer Dateien übernimmt der Server. Einzelheiten:
[[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].

== HTTP-Methode ==

Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
'''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.

== URL-Struktur ==

<pre>
http://[Host][:Port][Pfad-Template]
</pre>

Beispiele:
* <code>https://api.meinserver.de/orders</code>
* <code>https://api.meinserver.de/orders/4711</code>
* <code>https://api.meinserver.de/orders/4711/modules/A1</code>

== Versionierung ==

Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
<code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:

# Bestehenden Endpunkt unverändert lassen.
# Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
# Berechtigungen für neue Konsumenten setzen.
# Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist.

== Zugriffskontrolle ==

Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
dürfen.

{{Achtung|'''Ein Endpunkt besteht aus zwei Zeilen, und beide werden von Hand
gepflegt:''' der Eintrag in <code>RESTSRV_ENDPOINTS</code> und die Berechtigung
in <code>RESTSRV_ACCESS</code>. Fehlt die zweite, antwortet der Endpunkt
'''403''' - und sieht dabei fertig aus: Pfad, Skript und Server-Profil stehen
korrekt da, der Aufruf kommt trotzdem nicht durch. Das ist die häufigste Ursache
für ein „der Endpunkt ist doch angelegt" und kostet jedes Mal eine
Fehlersuche, weil der Statuscode nach einem Rechteproblem des Konsumenten
aussieht und nicht nach einer fehlenden Konfigurationszeile.

Beim Anlegen also '''immer beide Zeilen''', und beim Prüfen eines
<code>403</code> zuerst nachsehen, ob die zweite existiert.}} Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
<code>/orders/{uid}</code> erlauben, aber das ändernde
<code>PUT /orders/{uid}/modules/{code}</code> nicht).

== Caching ==

Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
(TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
zwingend sofort.

== HTTP-Fehlercodes ==

{| class="wikitable"
! Code !! Ursache
|-
| '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
|-
| '''403''' || Zugang fehlt in der Berechtigungsliste
|-
| '''401''' || API-Key ungültig/fehlend, JWT abgelaufen oder Sitzung gesperrt (''AUTH_EXPIRED'')
|-
| '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
|-
| '''405''' || Das Endpunkt-Skript hat für die angefragte HTTP-Methode keine Funktion; der Header <code>Allow</code> nennt die vorhandenen
|-
| '''206''' || Teilantwort eines Datei-Downloads auf eine <code>Range</code>-Anfrage; die Antwort enthält <code>Content-Range</code>
|-
| '''416''' || Der angefragte <code>Range</code> liegt hinter dem Dateiende; die Antwort nennt in <code>Content-Range</code> die wirkliche Grösse
|-
| '''415''' || Datei-Upload an einen Endpunkt, der dafür nicht freigeschaltet ist (<code>re_upload = 0</code>); oder ein <code>Content-Encoding</code>, das der Server nicht entpacken kann - unterstützt wird allein <code>gzip</code> (siehe [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]], Abschnitt Kompression)
|-
| '''413''' || Hochgeladene Datei überschreitet die zulässige Maximalgrösse (<code>re_upload_size</code>); oder der Anfragekörper überschreitet 10 MB bzw. - gepackt gesendet - das 400fache der gesendeten Grösse
|-
| '''429''' || Rate-Limit überschritten; die Antwort enthält den Header <code>Retry-After</code>
|-
| '''503''' || Vier Ursachen, unterscheidbar am <code>code</code>: <code>IDEMPOTENCY_IN_PROGRESS</code> (eine Anfrage mit demselben <code>Idempotency-Key</code> wird gerade verarbeitet), <code>SERVICE_UNAVAILABLE</code> bei erreichter Andrangsgrenze des Server-Profils (<code>rsv_max_parallel</code>), bei einer Anmeldung, deren Sitzungszeile nicht geschrieben werden konnte, sowie bei einem fehlgeschlagenen <code>JwtRevoke</code>. Alle vier tragen <code>Retry-After</code>
|-
| '''409''' || Ein früherer Aufruf mit demselben <code>Idempotency-Key</code> ist ohne Ergebnis geblieben (<code>IDEMPOTENCY_UNRESOLVED</code>)
|-
| '''422''' || Derselbe <code>Idempotency-Key</code> wurde mit '''anderem''' Inhalt gesendet (<code>IDEMPOTENCY_KEY_REUSED</code>)
|-
| '''400''' || Ein schreibender Aufruf (POST/PUT/PATCH/DELETE) '''ohne''' <code>Idempotency-Key</code> (<code>IDEMPOTENCY_KEY_MISSING</code>); ein resumable Upload ohne Dateinamen; oder eine Anfrage, die unverschlüsselt an einen TLS-Port geschickt wurde (<code>http</code> statt <code>https</code>) - letztere wird vor Authentifizierung und Endpunkt-Skript abgewiesen
|-
| '''308''' || Zwischenantwort beim resumable Upload: das Teilstück wurde angehängt, der Upload ist noch nicht vollständig. Die Antwort trägt <code>Upload-Id</code>, <code>Upload-Offset</code> und <code>Range</code>; das Skript läuft dabei '''nicht'''
|}

Jede Fehlerantwort besteht aus einem <code>error</code>-Objekt mit
maschinenlesbarem Code - Aufbau siehe
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].

Daneben kann ein Endpunkt-Skript den Statuscode selbst setzen (z.B. <code>201</code>, <code>204</code>, <code>409</code>, <code>422</code>) sowie Response-Header wie <code>ETag</code> oder <code>Location</code> - siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]].

== Idempotenz ==

Bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code>
sorgt der Server selbst dafür, dass eine wiederholte Sendung '''keine
Zweitwirkung''' hat. Das gilt für '''jeden''' Endpunkt - es muss weder am Endpunkt
etwas eingestellt noch im Skript etwas programmiert werden.

{{Achtung|'''Der Header <code>Idempotency-Key</code> ist bei diesen vier Verben
Pflicht.''' Fehlt er, antwortet der Server mit '''400'''
<code>IDEMPOTENCY_KEY_MISSING</code> und das Endpunkt-Skript läuft '''nicht''' an.

Bis v1.21 lief eine Anfrage ohne den Header ungeschützt durch; der Schutz gegen
die Doppelbuchung lag damit beim Client. Ausgenommen ist allein der
JWT-Endpunkt (Anmelden, Erneuern, Abmelden) - er greift vor der Adressauflösung
und kennt die Mechanik nicht.}}

{| class="wikitable"
! Situation !! Antwort des Servers
|-
| Kein <code>Idempotency-Key</code> gesendet || '''400''' <code>IDEMPOTENCY_KEY_MISSING</code>. Das Skript läuft nicht
|-
| Erster Aufruf || Endpunkt läuft normal, das Ergebnis wird zum Schlüssel gespeichert
|-
| Wiederholung, gleicher Inhalt || '''Gespeicherte Antwort''' (gleicher Statuscode, gleicher Body, gleiche Header) plus Header <code>Idempotent-Replay: true</code>. Das Skript läuft '''nicht'''
|-
| Wiederholung, anderer Inhalt || '''422''' <code>IDEMPOTENCY_KEY_REUSED</code> - derselbe Schlüssel für einen anderen Inhalt ist ein Client-Fehler
|-
| Erster Aufruf läuft noch || '''503''' <code>IDEMPOTENCY_IN_PROGRESS</code> mit <code>Retry-After</code>. Beim nächsten Versuch liegt die gespeicherte Antwort vor
|-
| Früherer Aufruf ohne Ergebnis || '''409''' <code>IDEMPOTENCY_UNRESOLVED</code>. Nur noch nach einem '''harten Abbruch''' des Dienstes zwischen Verarbeitung und Festschreiben; ob die Buchung stattgefunden hat, ist unbekannt. Der Aufräumlauf gibt solche Einträge nach 24 Stunden frei und protokolliert sie
|}

Wichtig für die Auslegung eines Endpunkts:

* Antwortet das Skript mit '''2xx''', wird die Antwort gespeichert und bei einer Wiederholung erneut ausgeliefert.
* '''Ausnahme Dateiantwort:''' Liefert das Skript mit <code>SendFile</code>/<code>SendTempFile</code> eine '''Datei''' aus, wird '''nichts''' festgeschrieben - eine Dateiantwort liesse sich nicht wiedergeben, gespeichert würde eine leere 200er-Antwort. Der Schlüssel wird stattdessen wieder freigegeben, ein erneuter Abruf derselben Datei ist unschädlich.
* Antwortet das Skript mit '''4xx''' (fachliche Ablehnung), wird der Schlüssel wieder '''freigegeben''' - der Konsument darf ihn nach Korrektur erneut verwenden. Sonst würde ein einziger Validierungsfehler den Schlüssel dauerhaft blockieren.
* Endet die Verarbeitung mit '''5xx''' oder einem Skript-Fehler, wird der Schlüssel '''freigegeben''' und der Fall protokolliert. Der Konsument darf denselben Schlüssel erneut senden.
* Das ist eine bewusste Abwägung (geändert 2026-08-25): Bleibt der Schlüssel nach einem Serverfehler belegt, ist der Vorgang '''unwiederholbar''' - der Client bekommt dauerhaft 503 und müsste die erfasste Arbeit verwerfen. Garantierter Datenverlust wiegt schwerer als ein möglicher Doppelsatz.
* '''Folge für die Auslegung:''' ein schreibender Endpunkt sollte selbst wiederholbar sein, etwa über ein fachliches Merkmal des Clients. Wo reines Anhängen stattfindet (Positionen, Dateien), bleibt sonst ein Restrisiko.

Der Schlüssel gilt je '''Zugang, Methode und Pfad'''. Derselbe
<code>Idempotency-Key</code> an einem anderen Endpunkt ist damit ein eigener
Vorgang - der Konsument muss ihn nicht global eindeutig vergeben, aber pro Vorgang
'''stabil wiederverwenden''' (also nicht bei jedem Wiederholversuch neu erzeugen).

Die Einträge stehen in <code>RESTSRV_IDEMPOTENCY</code>. Abgeschlossene Einträge
werden nach '''30 Tagen''' gelöscht. Einträge '''ohne Ergebnis''' - sie entstehen
nur bei einem harten Abbruch des Dienstes - werden ab '''24 Stunden''' im Protokoll
gemeldet und '''anschliessend ebenfalls gelöscht'''. Das Stehenlassen wäre keine
Vorsicht, sondern eine Sperre: derselbe Vorgang mit demselben Schlüssel wäre sonst
nie wieder durchführbar.

== WebHooks ==

WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
gespeichert und der Endpunkt anschließend automatisch gelöscht.

Typischer Einsatz: OBS stösst einen Vorgang bei einem Fremdsystem an (Bezahldienst,
Versanddienstleister) und gibt diesem eine Rückruf-Adresse mit, die nur '''ein
einziges Mal''' gültig ist. Damit kann die Adresse nicht später erneut - oder von
jemand anderem - benutzt werden.

Ablauf:

# OBS legt einen Eintrag in <code>REMOTE_HOOK_URL</code> an und dazu einen Endpunkt, dessen Feld '''WebHook''' (<code>re_webhook</code>) auf diesen Eintrag zeigt. Ein Skript wird für diesen Endpunkt nicht gepflegt.
# Die Adresse dieses Endpunkts wird dem Fremdsystem als Callback-URL übergeben.
# Das Fremdsystem ruft die Adresse auf. Der Server legt den übergebenen Inhalt in <code>REMOTE_HOOK_URL.hu_response</code> ab, antwortet mit <code>{"status": "ok"}</code> und '''löscht den Endpunkt'''.
# Der weiterverarbeitende OBS-Prozess findet die Rückmeldung in <code>hu_response</code>.

{{Hinweis|Ein zweiter Aufruf derselben Adresse läuft ins Leere: Der Endpunkt
existiert nicht mehr, die Antwort ist 404. Das ist gewollt - ein WebHook ist keine
dauerhafte Schnittstelle. Für eine dauerhaft erreichbare Rückmelde-Adresse einen
normalen Endpunkt mit Skript anlegen.}}

OBS/Kostenpflichtige Module/RESTServer

2026-09-25T09:28:32Z

MINERVA-Rademacker: Idempotency-Key als Pflicht, Abschnitt Keep-alive, HSTS, vollstaendige Konsolenbefehle; Ablaufliste und Protokollverhalten berichtigt [Volltext ersetzt]

{{Kostenpflichtige Module}}
=REST-Server=
{{Hinweis|Es handelt sich um ein kostenpflichtiges Modul. Die Schnittstelle muss über den OBS-Support aktiviert werden.}}

==Was leistet der REST-Server?==

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.

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

* '''Mobile Zeiterfassung:''' Mitarbeiter buchen Anfang, Pause und Ende über Smartphone oder Tablet, die Daten landen direkt in OBS - ohne Zettelwirtschaft.
* '''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===

* '''Webshops:''' Bestellungen werden direkt vom Shop in OBS gemeldet, Lagerbestände und Preise vom Shop bei OBS abgefragt.
* '''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)===

* '''Zahlungs-Callbacks:''' Bezahldienste (z.B. PayPal, Klarna, Stripe) melden den Zahlungseingang an einen WebHook-Endpunkt - OBS bucht automatisch.
* '''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)===

* '''Lieferanten-Schnittstelle:''' Bestellungen werden automatisch übergeben, Auftragsbestätigungen und Lieferavise zurückgespielt.
* '''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.

===Interne Microservices und Automatisierungen===

* '''Eigene kleine Hilfs-Tools:''' Zeitschaltautomatik, Reporting-Generator, Sammelaktionen, die aus mehreren Quellen Daten in OBS verarbeiten.
* '''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.

===Was bedeutet das wirtschaftlich?===

* '''Manuelle Arbeit fällt weg.''' Daten werden nicht mehr aus OBS exportiert, per Mail geschickt und woanders eingelesen - sie fliessen direkt.
* '''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:

{| 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-Beschränkung, optionale JWT-Konfiguration
|-
| Endpunkt || RESTSRV_ENDPOINTS || Skript, das die Anfrage bearbeitet, einem Server fest zugeordnet
|-
| Berechtigung || RESTSRV_ACCESS || Verbindet Zugang und Endpunkt
|-
| Idempotenz || RESTSRV_IDEMPOTENCY || Speicher für Idempotency-Keys und die dazu gelieferte Antwort
|-
| Sitzung || RESTSRV_TOKEN || Ausgestellte Token-Paare je Sitzung; Grundlage für Rotation und Widerruf
|-
| 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:

# 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"
! Anfrage !! Antwort
|-
| <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
|-
| <code>deflate</code>, anderer Wert (z.B. <code>br</code>) oder mehrere Werte || '''415''' <code>UNSUPPORTED_MEDIA_TYPE</code>
|-
| Gepackter Körper bei einem Datei-Upload || '''415''' - siehe [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
|-
| Entpackter Körper über '''10 MB''' || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|-
| Entpackter Körper über dem '''400fachen''' der gesendeten Grösse || '''413''' <code>PAYLOAD_TOO_LARGE</code>
|}

{{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:

* '''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"
! Grenze !! Wert !! Bedeutung
|-
| Leerlauf || '''10 Sekunden''' || Passiert auf der Verbindung so lange nichts, wird sie geschlossen
|-
| Anfragen je Verbindung || '''100''' || Danach schliesst der Server geordnet, der Client baut neu auf
|}

Beides ist für den Konsumenten unkritisch: Eine geschlossene Verbindung ist kein
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 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 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.

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

* 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"
! Befehl !! Wirkung
|-
| ''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
|-
| ''1'' … ''9'' || Auswahl im Kopfbereich - kürzer als ''show'' für die gerade sichtbaren Anfragen. Mit ''mouse on'' auch per Klick
|-
| ''ps'' || Listet die gerade laufenden Anfragen auf
|-
| ''level <stufe>'' || Anzeigestufe des Live-Logs: ''quiet'' , ''normal'' oder ''debug''. Ohne Parameter wird die aktuelle Stufe genannt
|-
| ''filter <ausdruck>'' || Blendet aus, was nicht passt: ''path=<text>'', ''account=<name>'', ''status>=<code>''. ''filter aus'' hebt die Einschränkung auf
|-
| ''panel on|off'' || Fixierten Kopfbereich ein-/ausschalten. '''Ausgeschaltet''' lässt sich der Rückblick-Puffer des Konsolenfensters wieder scrollen
|-
| ''mouse on|off'' || Klick-Auswahl im Kopfbereich. '''Eingeschaltet''' ist das Markieren von Text mit der Maus nicht mehr möglich
|-
| ''help'' / ''?'' || Zeigt diese Liste in der Konsole
|-
| ''exit'' / ''quit'' || Beendet den Server geordnet
|}

{{Hinweis|Der Anzeigefilter wirkt '''nur auf die Anzeige'''. Was die Konsole
ausblendet, steht vollständig in RESTSRV_PROTO - es geht nichts verloren.}}

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

==Weiterführende Seiten==

* [[OBS/Kostenpflichtige Module/RESTServer/Einrichtung|Einrichtung]] - Schritt-für-Schritt-Anleitung
* [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] - TLS, mTLS und Bindungen
* [[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/Scripting|Scripting]] - Aufbau der Endpunkt-Skripte
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]] - Übertragungsprotokoll für Dateien (Multipart, resumable)
* [[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]]