OBS Wiki - Benutzerbeiträge [de]

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]

{{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
|-
| Info || Freitext zur Dokumentation (interner Kommentar, wird nicht ausgewertet)
|-
| Kein SSL || Plain-HTTP-Modus, ausschliesslich für Debug. TLS-Felder werden ignoriert
|-
| mTLS || Mutual TLS: jeder Client muss ein gültiges Client-Zertifikat vorlegen
|-
| Cert || PEM-Inhalt des Server-Zertifikats (inkl. ggf. Zwischen-CA-Kette)
|-
| Key || PEM-Inhalt des privaten Schlüssels
|-
| Root-Cert || PEM-Inhalt des CA-Root-Zertifikats (Pflicht bei Standard-TLS, dort für Chain-Validierung, sowie bei mTLS, dort zusätzlich für Client-Cert-Verifikation)
|-
| Limit-Fenster || Länge des Rate-Limit-Fensters in Sekunden. Leer/0 = Standard 60
|-
| Limit Erfolg || Erlaubte erfolgreiche Anfragen je Schlüssel und Fenster. Leer/0 = Standard 120
|-
| Limit Fehler || Erlaubte fehlgeschlagene Anfragen je Schlüssel und Fenster. Leer/0 = Standard 10
|-
| Limit gesamt || 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. parallel || 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. parallel'' 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''' || Cert + Key + Root-Cert hinterlegt || Empfohlener Default für alle Server, die über das öffentliche Netz erreichbar sind
|-
| '''mTLS''' || Cert + Key + Root-Cert (CA) || 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 Cert/Key gar nicht erst hoch. Bei Standard-TLS ohne Root-Cert wird die Anlage abgelehnt - die Chain-Validierung benötigt das CA-Root. 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:''' Ein Zertifikatswechsel erfolgt durch ändern der PEM-Inhalte in der DB und einen '''Neustart''' des REST-Dienstes (kein Hot-Reload). Bis zum Neustart 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.
==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==

Beim Speichern wird geprüft:

* Nr und Name müssen vergeben sein.
* Nr muss eindeutig sein.
* Name muss eindeutig sein.
* Bei nicht aktiviertem ''Kein SSL'' müssen Cert und Key vorhanden sein.
* Bei nicht aktiviertem ''mTLS'' (= Standard-TLS) muss Root-Cert vorhanden sein.

==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/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]]