Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt]
 
(7 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
= Scripting =


=Anleitung für Endpunkt-Skripte=
Hinter jedem Endpunkt steht ein Skript, das Sie selbst schreiben. Damit bestimmen Sie, welche OBS-Daten ein Endpunkt liest oder ändert und was der Client zurückbekommt. Authentifizierung, Fehlerformat, Idempotenz und Transaktion übernimmt der Server. Diese Seite beschreibt die Skript-Schnittstelle: Anfrage lesen, Antwort schreiben, Fehler melden, gemeinsamen Code nutzen.


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.
Das Skript ist in Object Pascal geschrieben und nutzt die OBS-Funktionen für Datenbank und Hilfsfunktionen. Wie ein Client den Server aufruft, steht unter [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].


==Sicherheitshinweise==
== Aufruf ==
Je HTTP-Methode enthält das Skript eine gleichnamige '''Prozedur'''. Der Server ruft die Prozedur auf, die zur Methode der Anfrage passt:


{{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.}}
<syntaxhighlight lang="delphi">
procedure Get  (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post  (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put  (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch (oReader: TxRestReader; oWriter: TxRestWriter);
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);
</syntaxhighlight>


* Eingaben gegen erwartete Werte prüfen (z.B. Pflichtfelder, erlaubte Typen, Wertebereiche).
Ein Skript enthält nur die Methoden, die der Endpunkt anbietet. Fehlt die Methode zur Anfrage, antwortet der Server mit '''405''' <code>METHOD_NOT_ALLOWED</code>. Der Header <code>Allow</code> nennt die Methoden, die das Skript tatsächlich enthält:
* 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==
<syntaxhighlight lang="text">
HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT
</syntaxhighlight>


Pro HTTP-Methode wird im Skript eine gleichnamige Funktion implementiert. Der Server ruft genau die Funktion auf, die zur Methode des eingehenden Requests passt.
Lässt sich das Skript nicht übersetzen, antwortet der Server mit '''500'''. Die Meldung des Übersetzers mit Grund und Zeile steht im Protokoll.


function Get  (oParams: TStrings; oBody: TJSONObject): string;
== Parameter ==
function Post  (oParams: TStrings; oBody: TJSONObject): string;
{| class="wikitable"
function Put  (oParams: TStrings; oBody: TJSONObject): string;
! Parameter !! Typ !! Pflicht !! Standard !! Bedeutung
function Delete(oParams: TStrings; oBody: TJSONObject): string;
|-
function Patch (oParams: TStrings; oBody: TJSONObject): string;
| <code>oReader</code> || <code>TxRestReader</code> || ✓ || – || Die Anfrage: Query, Header, Pfadwerte, Formularfelder, Token-Werte, Körper und hochgeladene Datei. Siehe [[#Die Anfrage lesen: oReader|oReader]].
|-
| <code>oWriter</code> || <code>TxRestWriter</code> || ✓ || – || Die Antwort: Felder, Statuscode, Header, Fehler oder Datei. Siehe [[#Die Antwort schreiben: oWriter|oWriter]].
|}


Fehlt die zur Methode passende Funktion, antwortet der Server mit '''405 Method
Beide Objekte erzeugt und besitzt der Server. Im Skript wird nichts angelegt und nichts freigegeben. Die Datenbankverbindung steht im Skript global als <code>oDB</code> bereit.
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
== Sicherheitshinweise ==
Allow: GET, PUT
{{Achtung|Endpunkt-Skripte verarbeiten Daten aus dem Internet. Bauen Sie Werte des Clients nie ungeprüft in SQL ein. Setzen Sie jeden Wert über <code>DB_SQLVal</code> ein und prüfen Sie Eingaben gegen erlaubte Werte.}}


Ein im Vertrag zugesagtes Verb braucht also seine Funktion. Fehlt sie, ist das an
* Prüfen Sie Pflichtfelder, Typen und Wertebereiche.
der Antwort sofort zu erkennen und '''kein''' Serverfehler.
* Geben Sie nur zurück, was der Client braucht: keine internen Kennungen, keine Systemfelder, keine Passwörter.
* Lesen Sie Mandant und Rollen aus dem Token, nie aus Körper oder Query.
* Schreiben Sie keine internen Details in Fehlermeldungen. Die <code>message</code> geht an den Client.


==Parameter==
== Die Anfrage lesen: oReader ==
<code>oReader</code> ist der einzige Zugang zur Anfrage. Alle Werte sind Zeichenketten oder werden über einen typisierten Leser geholt.


===oParams (TStrings)===
{| class="wikitable"
 
! Aufruf !! Liefert
Enthält alle Query-Parameter, POST-Parameter (form-urlencoded) sowie die durchgereichten HTTP-Header. Werte sind immer Strings.
|-
 
| <code>oReader.Param('kundennr')</code> || Query-Parameter, Formularwert (<code>application/x-www-form-urlencoded</code>) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet.
Filterung durch den Server:
|-
 
| <code>oReader.Path('nr')</code> || Wert eines Platzhalters aus dem '''Pfad-Template'''
* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
|-
* Parameter mit Präfix '''_OBS_''' können von aussen nicht gesetzt werden; sie sind für interne Werte reserviert.
| <code>oReader.Form('bemerkung')</code> || Formularfeld einer <code>multipart/form-data</code>-Übertragung
* Werte werden auf max. 1024 Zeichen begrenzt.
|-
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.
| <code>oReader.Subject()</code> || Subject (<code>sub</code>) des vorgelegten Tokens
 
|-
Zugriff im Skript:
| <code>oReader.Claim('tenant')</code> || Eigener Claim des vorgelegten Tokens, als Text
 
|-
if (not Empty(oParams.Values['kundennr'])) then begin
| <code>oReader.TraceId()</code> || Kennung der Anfrage, gleich dem Header <code>X-Trace-Id</code> der Antwort
    cKundenNr := oParams.Values['kundennr'];
|-
end;
| <code>oReader.Offset()</code> || UTC-Offset des Servers, z.B. ''+01:00''
 
|-
===oBody (TJSONObject)===
| <code>oReader.HasBody()</code> || Wurde ein JSON-Körper gesendet?
 
|-
Enthält den Request-Body, sofern dieser ein gültiges JSON-Objekt ist. Bei leerem oder nicht-JSON-Body wird ''nil'' übergeben.
| <code>oReader.UploadPath()</code>, <code>UploadName()</code>, <code>UploadType()</code>, <code>UploadSha()</code> || Hochgeladene Datei, siehe [[#Datei-Uploads|Datei-Uploads]]
 
|}
{{Hinweis|'''Generics funktionieren im Skript nicht.''' Aus Delphi bekannte
Schreibweisen wie ''oBody.TryGetValue&lt;string&gt;('feld', cVar)'' lassen sich nicht
übersetzen. Gelesen wird über ''GetValue''.}}
 
''GetValue'' liefert ''nil'', wenn das Feld im Body '''nicht enthalten''' ist -
daran lässt sich „nicht gesendet" von „leer gesendet" unterscheiden. Der Wert ist
immer ein '''String''' und wird bei Bedarf selbst gewandelt.
 
cUser := '';
cPass := '';
if (Assigned(oBody)) then begin
    oVal := oBody.GetValue('username');
    if (Assigned(oVal)) then begin
        cUser := oVal.Value;
    end;
    oVal := oBody.GetValue('password');
    if (Assigned(oVal)) then begin
        cPass := oVal.Value;
    end;
end;


Bei mehr als zwei Feldern lohnt eine kleine Hilfsfunktion, die das Muster einmal
Was der Server vorher filtert:
kapselt:
* Die Header <code>authorization</code>, <code>cookie</code>, <code>proxy-authorization</code>, <code>x-forwarded-for</code>, <code>x-real-ip</code>, <code>apikey</code> und <code>api_key</code> erreichen das Skript nicht.
* Namen, die mit <code>_OBS_</code> beginnen, sind dem Server vorbehalten. Header und Query-Parameter mit solchen Namen verwirft er.
* Werte aus Header, Query, Pfad und Formular kürzt er nach 1024 Zeichen.
* Null-Bytes und Steuerzeichen entfernt er. Tabulator, CR und LF bleiben.


<syntaxhighlight lang="pascal" line>
<syntaxhighlight lang="delphi">
function _BodyStr(oBody: TJSONObject; const cFeld: string): string;
cKundenNr := oReader.Param('kundennr');
var oVal: TJSONValue;
if (not Empty(cKundenNr)) then begin
begin
    // ...
    result := '';
    if (oBody = nil) then begin
        exit;
    end;
    oVal := oBody.GetValue(cFeld);
    if (Assigned(oVal)) then begin
        result := oVal.Value;
    end;
end;
end;
// Aufruf:
cBetreff := _BodyStr(oBody, 'betreff');
</syntaxhighlight>
</syntaxhighlight>


Andere Typen entstehen aus dem String:
=== Der Körper ===
Den JSON-Körper liest <code>oReader</code> über '''Pfade'''. Es gibt keine Unterobjekte, keine Typumwandlung und nichts freizugeben.


{| class="wikitable"
{| class="wikitable"
! Zieltyp !! Umwandlung
! Aufruf !! Bedeutung
|-
|-
| Ganzzahl || <code>iVal(_BodyStr(oBody, 'menge'))</code>
| <code>oReader.Str('betreff', cWert)</code> || Liest den Wert. '''Rückgabe Boolean''': War das Feld da? Fehlt es, bleibt die Variable unverändert.
|-
|-
| Kommazahl || <code>fVal(StrTran(_BodyStr(oBody, 'preis'), '.', ','))</code> - '''JSON liefert den Dezimalpunkt''', ''fVal'' erwartet die lokale Notation
| <code>oReader.Int('menge', nWert)</code> || dito, Ganzzahl
|-
|-
| Boolean || <code>Lower(_BodyStr(oBody, 'aktiv')) = 'true'</code>
| <code>oReader.Num('preis', nWert)</code> || dito, Kommazahl. Den Dezimalpunkt aus JSON liest der Reader richtig.
|-
|-
| Datum/Zeit || ISO-8601-String selbst zerlegen (''CToDT'' erwartet das deutsche Format)
| <code>oReader.Bool('aktiv', lWert)</code> || dito, Boolean
|}
 
Maximale Body-Grösse: 10 MB.
 
===Reservierte _OBS_-Parameter===
 
Bei aktiver JWT-Authentifizierung stehen die Token-Claims als Parameter zur Verfügung:
 
{| class="wikitable"
! Parameter            !! Inhalt
|-
|-
| _OBS_JWT_ID          || 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.NumDef('rabatt', nWert, 0)</code> || wie <code>Num</code>, mit Vorgabewert
|-
|-
| _OBS_JWT_SUBJECT    || Subject (''sub''-Claim) - typisch Benutzername
| <code>oReader.Has('feld')</code> || Ist das Feld vorhanden, auch mit <code>null</code>?
|-
|-
| _OBS_JWT_AUDIENCE    || Audience (''aud''-Claim) - typisch Mandant / Rolle
| <code>oReader.Count('zeiten')</code> || Anzahl Einträge einer Liste, 0 wenn keine Liste
|-
|-
| _OBS_JWT_CLAIM_&lt;name&gt; || Beliebiger Custom-Claim des Tokens (z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles); im Folge-Skript lesbar
| <code>oReader.IsArr('zeiten')</code>, <code>oReader.IsObj('zeiten[0]')</code> || Ist der Wert eine Liste bzw. ein Objekt?
|-
|-
| _OBS_TRACE_ID        || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
| <code>oReader.Keys()</code> || Alle Feldnamen der obersten Ebene, in Kommas eingefasst
|}
|}


Unabhängig von JWT stehen ausserdem immer zur Verfügung:
Verschachtelung steht im Pfad: Punkt für Felder, eckige Klammern für Listen.
 
<syntaxhighlight lang="delphi">
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>


{| class="wikitable"
{{Hinweis|Der Rückgabewert unterscheidet „nicht gesendet“ von „leer gesendet“. Bei <code>"feld": null</code> liefert <code>oReader.Str('feld', cWert)</code> ''true'' und einen leeren Wert, bei fehlendem Feld ''false''. So unterscheidet ein PATCH „Feld leeren“ von „Feld nicht ändern“.}}
! Parameter            !! Inhalt
|-
| _OBS_SERVER_TIME    || 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
|-
| _OBS_JWT_EXP_SEC    || 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.
Regeln für den Körper:
* Der Server liest den Körper als UTF-8.
* Nur ein JSON-'''Objekt''' als Wurzel gilt als Körper. Eine Liste als Wurzel oder ungültiges JSON ergibt keinen Körper: <code>HasBody()</code> ist ''false'', jeder Leser liefert ''false''. Der Server antwortet in diesem Fall nicht mit 400. Prüfen Sie Pflichtfelder deshalb im Skript.
* Ein Körper ohne Datei darf höchstens 10 MB groß sein, auch nach dem Entpacken. Darüber antwortet der Server mit '''413''', das Skript läuft nicht. Gepackte Körper: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Kompression|HTTP-Schnittstelle]].


Zusätzlich trägt jedes Token zwei '''Sitzungskennungen des Servers''', lesbar als
=== Werte des Servers ===
''_OBS_JWT_CLAIM_sid'' und ''_OBS_JWT_CLAIM_rid'':
Diese Werte setzt der Server. Ein Client kann sie nicht überschreiben.


{| class="wikitable"
{| class="wikitable"
! Claim !! Inhalt
! Aufruf !! Inhalt
|-
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Serverzeit nach ISO 8601 mit UTC-Offset, z.B. ''2026-11-17T09:12:33+01:00''
|-
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+01:00''. Er geht in die [[#Zeitangaben|Zeitfunktionen]].
|-
|-
| sid || Sitzung. Bleibt über alle Erneuerungen (Refresh) hinweg gleich und ist der Schlüssel für das Abmelden
| <code>oReader.TraceId()</code> || Kennung der Anfrage
|-
|-
| rid || Zeilenkennung des einzelnen Token-Paares in ''RESTSRV_TOKEN''. Bei jeder Erneuerung neu
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden ('''Lebenszeit (Min)''' × 60)
|}
|}


Beide sind OBS-UIDs (10 Zeichen) und werden vom Server '''nach''' den Claims des
Bei Zugängen mit '''JWT-Authentifizierung''' stehen zusätzlich die Werte des Tokens bereit: <code>oReader.Subject()</code>, <code>oReader.Claim('&lt;name&gt;')</code>, <code>oReader.Param('_OBS_JWT_ID')</code>, <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> sowie die Sitzungskennungen <code>sid</code> und <code>rid</code>. Die vollständige Liste steht unter [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Claims im Endpunkt lesen|Anmeldung mit JWT]].
Skripts gesetzt - ein Skript kann sie also auch mit ''_OBS_JWT_CLAIM_sid'' nicht
überschreiben. Für Fachlogik sind sie nicht gedacht; sie sind nützlich, um eine
Sitzung im Protokoll wiederzufinden.


===Pfad-Parameter===
=== Pfad-Parameter ===
 
Enthält das '''Pfad-Template''' Platzhalter, liefert <code>oReader.Path</code> deren Werte:
Stammt der Endpunkt aus einem Pfad-Template mit Platzhaltern (siehe [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]), stehen die aus den Platzhaltern erfassten Werte als reservierte Parameter mit Präfix '''_OBS_PATH_''' in ''oParams'' bereit:


{| class="wikitable"
{| class="wikitable"
! Template !! Zugriff im Skript
! Pfad-Template !! Zugriff im Skript
|-
|-
| <code>/orders/{uid}</code> || ''oParams.Values['_OBS_PATH_uid']''
| <code>/beispiel/auftraege/{nr}</code> || <code>oReader.Path('nr')</code>
|-
|-
| <code>/orders/{uid}/modules/{code}</code> || ''oParams.Values['_OBS_PATH_uid']'', ''oParams.Values['_OBS_PATH_code']''
| <code>/beispiel/auftraege/{nr}/module/{code}</code> || <code>oReader.Path('nr')</code>, <code>oReader.Path('code')</code>
|}
|}


Da der Präfix ''_OBS_'' für von aussen gelieferte Header- und Query-Parameter gesperrt ist, sind diese Werte nicht durch den Client fälschbar. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].
Der '''Name''' ist geschützt: Ein Client kann einen Pfadwert nicht über Query oder Header unterschieben. Der '''Wert''' stammt aber aus der URL des Clients. Prüfen Sie ihn wie jede andere Eingabe, z.B. ob der Auftrag zum Mandanten im Token gehört. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4]].
 
===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 reservierte
Parameter. Das Skript entscheidet selbst über die weitere Verarbeitung (z.B.
DMS-Ablage). Der Body wird in diesem Fall '''nicht''' als JSON geparst - ''oBody''
ist ''nil''. Es gilt nicht das JSON-Body-Limit (10&nbsp;MB), sondern die pro
Endpunkt konfigurierte Grösse (''re_upload_size'', Standard 25&nbsp;MB;
Überschreitung -> 413).


Beide Übertragungsarten - <code>multipart/form-data</code> und der resumable
=== Datei-Uploads ===
<code>Content-Range</code>-Upload - liefern dem Skript dieselben Parameter:
Hat der Endpunkt den Haken '''Datei-Upload''', nimmt der Server Dateien entgegen und legt sie in einem temporären Verzeichnis ab. Das Skript erhält die Datei über diese Aufrufe:


{| class="wikitable"
{| class="wikitable"
! Parameter !! Inhalt
! Aufruf !! Inhalt
|-
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei auf dem Server
| <code>oReader.UploadPath()</code> || Vollständiger Pfad der temporären Datei auf dem Server
|-
|-
| _OBS_UPLOAD_NAME || Originaldateiname
| <code>oReader.UploadName()</code> || Originaler Dateiname
|-
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)
| <code>oReader.UploadType()</code> || Content-Type der Datei, kleingeschrieben. Ohne Angabe des Clients <code>application/octet-stream</code>.
|-
|-
| _OBS_UPLOAD_SHA256 || 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
| <code>oReader.UploadSha()</code> || SHA-256 der gespeicherten Datei, hexadezimal in Kleinbuchstaben. Vergleichen Sie damit eine Prüfsumme, die der Client mitsendet.
|}
|}


Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
* Beide Übertragungswege liefern dieselben Werte: <code>multipart/form-data</code> und der fortsetzbare Upload mit <code>Content-Range</code>. Beim fortsetzbaren Upload läuft das Skript erst, wenn die Datei vollständig ist.
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
* Ohne Dateinamen weist der Server den Upload mit '''400''' ab, das Skript läuft nicht. <code>UploadPath()</code> und <code>UploadName()</code> sind im Skript also immer gefüllt.
sich also darauf verlassen, dass ''_OBS_UPLOAD_PATH'' und ''_OBS_UPLOAD_NAME''
* Ein Upload-Körper wird nicht als JSON gelesen. <code>HasBody()</code> ist ''false''.
gesetzt sind, sobald es läuft.
* Zusatzangaben eines Formulars liest das Skript mit <code>oReader.Form('&lt;name&gt;')</code>. Das sind die Partien ohne <code>filename=</code>. Vom Namen bleiben nur Buchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen.
 
* Beim fortsetzbaren Upload gibt es keine Formularfelder. Zusatzangaben kommen dort über Query-Parameter oder Header.
{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}
* Ein Upload an einen Endpunkt ohne '''Datei-Upload''' beantwortet der Server mit '''415'''. Überschreitet die Übertragung die '''maximale Dateigröße (MB)''' des Endpunkts, antwortet er mit '''413'''.


====Einfacher Upload (multipart/form-data)====
{{Hinweis|Der Server verschiebt die temporäre Datei nicht. Das Skript übernimmt sie an ihren Zielort.}}


Eine Datei pro Request. Name und Content-Type stammen aus der
Übertragung, Header und Statuscodes: [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Beispiel 6]].
<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> -
== Die Antwort schreiben: oWriter ==
übergibt der Server als <code>_OBS_FORM_&lt;name&gt;</code>. Der Wert ist UTF-8 und
Der Writer schreibt '''der Reihe nach''': Jeder Aufruf hängt ein Feld an der Stelle an, an der er steht. Die äußere Klammer setzt der Server. Schreibt das Skript nichts, lautet die Antwort <code>{}</code>. Ohne weitere Angabe ist der Status 200 und der Content-Type <code>application/json; charset=utf-8</code>.
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>
<syntaxhighlight lang="delphi">
function Post(oParams: TStrings; oBody: TJSONObject): string;
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var oRes : TJSONObject;
    cPfad: string;
    cName: string;
    cTyp : string;
begin
begin
     oRes := TJSONObject.Create();
     oWriter.Str('wert_string', '123');
    try
    oWriter.Int('wert_int'   , 456);
        cPfad := oParams.Values['_OBS_UPLOAD_PATH'];
        cName := oParams.Values['_OBS_UPLOAD_NAME'];
        cTyp  := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];
 
        // ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...
 
        oRes.AddPair('status'   , 'ok');
        oRes.AddPair('dateiname', cName);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
end;
end;
</syntaxhighlight>
</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'''
(dann mit gesetztem ''_OBS_UPLOAD_PATH'', ''_OBS_UPLOAD_NAME'' und
''_OBS_UPLOAD_CONTENTTYPE'').
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"
{| class="wikitable"
! Request !! Server-Antwort
! Aufruf !! Ergebnis
|-
|-
| 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>
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
| <code>oWriter.StrN('name', cWert)</code> || wie <code>Str</code>, aber <code>null</code> statt einer leeren Zeichenkette
|-
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. Immer mit Dezimalpunkt, unabhängig von den Ländereinstellungen des Servers.
|}
|-
 
| <code>oWriter.Bool('aktiv', lWert)</code> || <code>true</code> oder <code>false</code>
{| class="wikitable"
! Header !! Richtung !! Bedeutung
|-
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
| <code>oWriter.Null('lat')</code> || ausdrücklich <code>null</code>
|-
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
|-
| 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.
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
| <code>oWriter.RootArr()</code> || Die Wurzel ist eine Liste statt eines Objekts. Steht vor dem ersten Feld. Ein <code>ArrEnd</code> gehört nicht dazu.
|-
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
| <code>oWriter.Raw('meta', cJson)</code> || Fertiges JSON-Fragment einbetten, siehe unten
|}
|}


Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
'''In einer Liste hat ein Eintrag keinen Namen.''' Der leere Feldname steht dafür:
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''),
<syntaxhighlight lang="delphi">
antwortet der Server mit '''413 Payload Too Large'''.
oWriter.ArrBegin('dateien');
while (not qDat.EoF) do begin
    oWriter.ObjBegin('');
    oWriter.Str ('uid'      , qDat.A2C('f_uid'));
    oWriter.Int ('bytes'   , qDat.A2I('f_bytes'));
    oWriter.StrN('kategorie', AllTrim(qDat.A2C('f_kat')));  // null, wenn leer
    oWriter.ObjEnd;
    qDat.Next();
end;
oWriter.ArrEnd;
</syntaxhighlight>


{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}
Ein Name in einer Liste, ein fehlender Name in einem Objekt und eine Ebene, die am Ende der Methode noch offen ist, sind '''Strukturfehler'''. Der Server antwortet dann mit '''500''' und nennt die Stelle im Protokoll. Halbes JSON liefert er nie aus.


==Rückgabe==
{{Hinweis|Eine Hilfsprozedur bekommt den Writer als Parameter und schreibt an der Stelle, an der sie aufgerufen wird. Sie gibt kein Fragment zurück. So steht die Reihenfolge der Antwort im Code:


Die Rückgabe ist immer ein '''JSON-String'''. Wird ein leerer String zurückgegeben, antwortet der Server automatisch mit ''{}''. Der Server setzt Content-Type auf ''application/json; charset=utf-8'' und Status auf 200, sofern das Skript nicht selbst einen Fehler signalisiert.
<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}


Einfaches Beispiel:
<code>Raw</code> prüft das Fragment und bettet den Originaltext ein. Ungültiges JSON führt zu einem Serverfehler, der das Feld nennt. Gebraucht wird <code>Raw</code> für gespeicherte, '''signierte''' Dokumente: Neu aufgebaut, verlöre das Dokument die signierte Reihenfolge der Felder.


<syntaxhighlight lang="pascal" line>
=== Zeitangaben ===
function Get(oParams: TStrings; oBody: TJSONObject): string;
Zeitpunkte gehen als ISO 8601 mit Offset über die Leitung. Für die Umwandlung gibt es eigene Funktionen:
var oRes: TJSONObject;
begin
    oRes := TJSONObject.Create();
    try
        oRes.AddPair('wert_string', '123');
        oRes.AddPair('wert_int'  , 456);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
end;
</syntaxhighlight>


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


Ein Skript kann den HTTP-Statuscode und beliebige Response-Header über reservierte Felder in der Antwort setzen. Der Server wertet sie aus und entfernt sie vor dem Senden aus dem Body.
== Antwort steuern: Statuscode, Header, traceId ==
Statuscode, Header, Fehler und Dateien setzen eigene Aufrufe des Writers, nicht Felder im Körper.


{| class="wikitable"
{| class="wikitable"
! Antwort-Feld !! Wirkung
! Aufruf !! Wirkung
|-
| <code>oWriter.Status(201)</code> || HTTP-Statuscode, z.B. 201, 204, 409 oder 422. Ohne Angabe: 200. Werte außerhalb von 100 bis 599 ignoriert der Server.
|-
| <code>oWriter.Header('ETag', '"7"')</code> || Beliebiger Header der Antwort, z.B. <code>ETag</code>, <code>Location</code>, <code>Retry-After</code>. Steuerzeichen in Name und Wert entfernt der Server.
|-
|-
| _OBS_HTTP_STATUS (Zahl) || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200. Bei 204 wird kein Body gesendet.
| <code>oWriter.NoBody()</code> || Kein Körper, für '''204'''
|-
|-
| _OBS_HEADERS (Objekt) || Beliebige Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen/Werten werden entfernt (Schutz vor Header-Injection).
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt')</code> || Fertige Fehlerantwort im Format des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
|-
| _OBS_JWT_REVOKE (Text) || 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.HasError()</code> || Steht schon eine Fehlerantwort im Writer?
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens, mit <code>'all'</code> alle Sitzungen des Subjects. Siehe [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Abmelden aus einem Endpunkt|Anmeldung mit JWT]].
|-
| <code>oWriter.SendFile(cPfad, cName, cTyp)</code> || Eine Datei statt eines JSON-Körpers ausliefern. Die Datei bleibt liegen, der Download ist fortsetzbar.
|-
| <code>oWriter.SendTempFile(cPfad, cName, cTyp)</code> || Wie <code>SendFile</code>, die Datei wird nach dem Senden gelöscht. Für Ergebnisse, die je Abruf entstehen.
|}
|}


Zusätzlich trägt jede Antwort den Header '''X-Trace-Id''' (Korrelations-ID). Dieselbe ID liegt dem Skript als ''oParams.Values['_OBS_TRACE_ID']'' vor und erscheint in jeder Server-Fehler-Logzeile in '''RESTSRV_PROTO''' - so lässt sich ein Fehler ohne Gerätezugriff im Log wiederfinden.
Dateiantworten beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]].


===Beispiel: Anlegen mit 201, Location und ETag===
Jede Antwort trägt den Header <code>X-Trace-Id</code>. Dieselbe Kennung liefert <code>oReader.TraceId()</code>, und sie steht in jeder Fehlerzeile des Protokolls. So findet der Betreiber einen Fehler ohne Zugriff auf das Gerät.


<syntaxhighlight lang="pascal" line>
Setzt das Skript den Header <code>Content-Encoding</code> selbst, packt der Server die Antwort nicht noch einmal.
function Post(oParams: TStrings; oBody: TJSONObject): string;
 
var oRes, oHdr: TJSONObject;
=== Beispiel: Anlegen mit 201, Location und ETag ===
<syntaxhighlight lang="delphi">
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueNr: string;
begin
begin
     oRes := TJSONObject.Create();
     // ... Datensatz anlegen, neue Nummer ermitteln ...
    try
        // ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...
        oHdr := TJSONObject.Create();
        oHdr.AddPair('Location', '/v1/orders/' + cNeueUid);
        oHdr.AddPair('ETag', '1');


        oRes.AddPair('_OBS_HTTP_STATUS', 201);
    oWriter.Str('nr', cNeueNr);
        oRes.AddPair('_OBS_HEADERS', oHdr);
    oWriter.Status(201);
        oRes.AddPair('uid', cNeueUid);
    oWriter.Header('Location', '/beispiel/tickets/' + cNeueNr);
        result := oRes.ToJSON();
    oWriter.Header('ETag'    , '"1"');
    finally
        MyFreeAndNil(oRes);
    end;
end;
end;
</syntaxhighlight>
</syntaxhighlight>


===Beispiel: Strukturierter Fehler mit Statuscode und traceId===
=== Beispiel: Versionsprüfung mit ETag und If-Match ===
Mit Statuscode, Header und dem Header <code>If-Match</code> der Anfrage führt das Skript je Datensatz einen Versionszähler. Veraltete Schreibzugriffe lehnt es mit '''409''' ab. Clients senden den ETag meist in Anführungszeichen (<code>"7"</code>), manche ohne.


<syntaxhighlight lang="pascal" line>
<syntaxhighlight lang="delphi">
function Post(oParams: TStrings; oBody: TJSONObject): string;
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var oRes, oErr: TJSONObject;
var nAktuell: Integer;
    cETag  : string;
    cIfMatch: string;
begin
begin
     oRes := TJSONObject.Create();
     nAktuell := TicketVersion(oReader.Path('nr'));   // eigene Funktion
     try
     cETag    := '"' + IntToStr(nAktuell) + '"';
        oErr := TJSONObject.Create();
    cIfMatch := AllTrim(oReader.Param('if-match'));
        oErr.AddPair('code', 'VALIDATION_FAILED');
        oErr.AddPair('message', 'Feld "menge" fehlt');
        oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);


         oRes.AddPair('_OBS_HTTP_STATUS', 422);
    if (cIfMatch <> cETag) and (cIfMatch <> IntToStr(nAktuell)) then begin
         oRes.AddPair('error', oErr);
        // Der gültige ETag gehört auch an die Ablehnung,
         result := oRes.ToJSON();
         // sonst scheitert der nächste Versuch des Clients wieder.
    finally
        oWriter.Header('ETag', cETag);
        MyFreeAndNil(oRes);
         oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geändert');
         exit;
     end;
     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>
function Put(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oHdr: TJSONObject;
    nAktuell, nIfMatch: integer;
begin
    oRes := TJSONObject.Create();
    try
        nAktuell := AuftragVersion(oParams.Values['_OBS_PATH_uid']);
        nIfMatch := iVal(oParams.Values['if-match']);
        if (nIfMatch <> nAktuell) then begin
            oHdr := TJSONObject.Create();
            oHdr.AddPair('ETag', xStr(nAktuell));
            oRes.AddPair('_OBS_HTTP_STATUS', 409);
            oRes.AddPair('_OBS_HEADERS', oHdr);
            oRes.AddPair('error', TJSONObject.Create.AddPair('code', 'VERSION_CONFLICT'));
            result := oRes.ToJSON();
            exit;
        end;


        // ... speichern, Version hochzählen ...
    // ... speichern, Version hochzählen ...
        oHdr := TJSONObject.Create();
    oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
        oHdr.AddPair('ETag', xStr(nAktuell + 1));
        oRes.AddPair('_OBS_HEADERS', oHdr);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
end;
end;
</syntaxhighlight>
</syntaxhighlight>


==Idempotenz - was das Skript beachten muss==
<code>VERSION_CONFLICT</code> ist hier ein eigener Code des Skripts. Der Server selbst verwendet für '''409''' den Code <code>CONFLICT</code>.


Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
== Transaktion ==
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
<code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code> laufen in '''einer''' Datenbanktransaktion. Darin liegen alle Schreibvorgänge des Skripts und das Ergebnis der Idempotenz-Prüfung.
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.
 
Was das Skript wissen muss:


{| class="wikitable"
{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
! Ende des Skripts !! Wirkung
|-
|-
| '''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
| Status unter 400 || Alle Änderungen werden festgeschrieben.
|-
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
| Status 400 oder höher || Alle Änderungen werden zurückgerollt.
|-
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
| Exception oder Skriptfehler || Alle Änderungen werden zurückgerollt, der Client erhält '''500'''.
|}
|}


Daraus folgen zwei Regeln für Endpunkt-Skripte:
* '''Ablehnen ist gefahrlos.''' Ein Skript darf schreiben und danach mit <code>oWriter.Error</code> abbrechen. In der Datenbank bleibt nichts davon.
* '''Auch eigene Protokollzeilen''', die das Skript in eine Tabelle schreibt, werden bei Status 400 oder höher zurückgerollt. Die Fehlerzeile des Servers in <code>RESTSRV_PROTO</code> bleibt, siehe [[#Fehler im Protokoll|Fehler im Protokoll]].
* '''Eigene Transaktionen''' im Skript (<code>StartTransaction</code>, <code>Commit</code>) sind wirkungslos. Sie liegen innerhalb der Transaktion des Servers, und nur deren Ende zählt.
* '''Teilweise Schreibvorgänge''' bleiben nur stehen, wenn das Skript einen Schreibfehler übergeht und mit Status unter 400 antwortet. Werten Sie deshalb jeden Schreibvorgang aus, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]].


* '''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.
<code>GET</code> läuft '''ohne''' Transaktion. Schreibt ein GET-Skript, wirkt jeder Schreibvorgang sofort und bleibt auch bei einer Fehlerantwort stehen.
* '''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.


{{Hinweis|Vor dieser Server-Funktion mussten Skripte die Idempotenz selbst
== Idempotenz ==
abbilden. Solche Skripte laufen unverändert weiter - die Doppelprüfung schadet
Bei <code>POST</code>, <code>PUT</code>, <code>PATCH</code> und <code>DELETE</code> fängt der Server doppelte Sendungen über den Header <code>Idempotency-Key</code> ab. Das Skript braucht dafür keine eigene Logik. Fehlt der Header, läuft das Skript nicht.
nicht, ist aber überflüssig und kann beim nächsten Überarbeiten entfallen.}}


Der vollständige Ablauf und die Statuscodes stehen unter
Für das Skript gilt:
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].
* Eine Wiederholung mit gespeicherter Antwort beantwortet der Server selbst. Das Skript läuft dabei nicht.
* Gespeichert wird nur eine Antwort mit Status 2xx ohne Datei. Was sie enthält, ist eingefroren. Schreiben Sie die Antwort deshalb vollständig.
* Melden Sie fachliche Ablehnungen mit 4xx (z.B. 404, 409, 422), nicht mit 200 und Fehlertext. Eine 2xx-Antwort würde gespeichert, und der Client bekäme sie bei jedem weiteren Versuch erneut.
* Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos.


==JWT-Authentifizierungs-Skript==
Den Ablauf aus Sicht des Clients beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].


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:
== Fehlerbehandlung im Skript ==
Löst das Skript eine Exception aus oder lässt es sich nicht übersetzen, antwortet der Server mit '''500''' <code>INTERNAL_ERROR</code> und einer allgemeinen Meldung. Den Fehlertext schreibt er ins Protokoll. Der Client sieht keine internen Details.


<syntaxhighlight lang="pascal" line>
Für einen gezielten Fehler gibt es '''einen''' Aufruf. Er erzeugt dieselbe Fehlerantwort wie die Fehler des Servers: Statuscode, <code>code</code>, <code>message</code>, <code>uid</code> und <code>traceId</code>.
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
 
var oRes  : TJSONObject;
<syntaxhighlight lang="delphi">
    oVal  : TJSONValue;
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
    cUser : string;
    cPass : string;
begin
begin
     oRes := TJSONObject.Create();
     if (Empty(oReader.Param('kundennr'))) then begin
    try
         oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
        // Eingangsdaten lesen (Body oder Query-Param)
         exit;
        cUser := '';
        cPass := '';
        if (Assigned(oBody)) then begin
            oVal := oBody.GetValue('username');
            if (Assigned(oVal)) then begin
                cUser := oVal.Value;
            end;
            oVal := oBody.GetValue('password');
            if (Assigned(oVal)) then begin
                cPass := oVal.Value;
            end;
        end;
 
        // Prüfung gegen eigene Tabelle, Hash-Verfahren, LDAP, ...
        if (PasswortPasst(cUser, cPass)) then begin
            oRes.AddPair('status'          , 1);
            oRes.AddPair('_OBS_JWT_ID'    , cUser);
            oRes.AddPair('_OBS_JWT_SUBJECT', cUser);
            oRes.AddPair('_OBS_JWT_AUDIENCE', 'mandant1');
         end else begin
            oRes.AddPair('status', 9);
            oRes.AddPair('error' , 'Login fehlgeschlagen');
         end;
 
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
     end;
     end;
    // ...
end;
end;
</syntaxhighlight>
</syntaxhighlight>


Rückgabewerte:
{{Hinweis|<code>Error</code> verwirft einen schon begonnenen Körper und setzt die Fehlerantwort. Ein Skript darf also Felder schreiben und danach noch abbrechen. Nur eine noch offene Ebene (<code>ObjBegin</code> ohne <code>ObjEnd</code>) bleibt ein Strukturfehler.}}


{| class="wikitable"
Codes, die auch der Server verwendet: <code>VALIDATION_FAILED</code> (422), <code>NOT_FOUND</code> (404), <code>FORBIDDEN_ROLE</code> (403), <code>CONFLICT</code> (409). Eigene, fachlich sprechende Codes sind erlaubt. Halten Sie sie stabil, denn Clients richten ihre Reaktion danach aus. Alle Codes des Servers: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].
! 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'''
=== Fehler im Protokoll ===
und wird typischerweise direkt unter dem Passwortfeld angezeigt. Er sollte für
Jede Antwort des Skripts mit Status 400 oder höher schreibt der Server als eine Zeile nach <code>RESTSRV_PROTO</code>, mit <code>code</code> und <code>message</code> aus dem Fehlerobjekt:
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
<syntaxhighlight lang="text">
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
Fehler VALIDATION_FAILED [422 POST /beispiel/tickets] [trace=<traceId>]: Parameter "kundennr" fehlt
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
</syntaxhighlight>
„Passwort falsch" erscheinen.


Kann der Server die '''Sitzungszeile''' zum ausgestellten Token nicht schreiben
Daraus folgt:
(Tabelle fehlt, Datenbankproblem), liefert er '''kein Token''' aus und antwortet
* Verwenden Sie <code>oWriter.Error</code>. Ohne Fehlerobjekt steht im Protokoll nur der Code aus dem Status und der Text „Antwort ohne error-Objekt“.
mit '''503''' und ''Retry-After''. Auch das ist bewusst kein 401/403: die
* Schreiben Sie keine sensiblen Daten in die <code>message</code>. Sie steht im Protokoll und geht an den Client.
Zugangsdaten waren richtig, der Versuch darf wiederholt werden.
* Schreiben Sie für dieselbe Ablehnung keine eigene Protokollzeile. Der Server hat sie bereits.


===Aufbau der Token-Antwort===
Protokoll und Suche über die <code>traceId</code>: [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]].


Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
== Datenbankzugriff ==
Feldern, die das Skript zurückgibt''':
Im Skript beginnt jede Datenbankfunktion mit <code>oDB</code>, ohne weiteren Parameter davor. Der Abfragetyp für <code>DB_SOpen</code> ist <code>TxFQuery</code>.
 
{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
  "token":      "eyJ...",
  "accessToken": "eyJ...",
  "refreshToken":"eyJ...",
  "expiresIn":  28800,
  "serverTime":  "2026-08-17T09:12:33+02:00"}


{| class="wikitable"
{| class="wikitable"
! Feld !! Herkunft
! Zweck !! Aufruf
|-
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
| Lesen || <code>DB_SOpen(oDB, cSql, qDat)</code>, dann <code>qDat.EoF</code>, <code>qDat.Next()</code>, <code>qDat.A2C('feld')</code>, <code>A2I</code>, <code>A2F</code>, <code>A2D</code>, <code>A2UID()</code>, am Ende <code>DB_Close(qDat)</code>
|-
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
| Neu anlegen || <code>qUpd := qSqlInit(oDB, 'TAB')</code>, <code>qUpd.qSet('feld', wert)</code>, <code>qUpd.SaveData(NEW_RECORD)</code> auswerten, <code>qSqlFree(qUpd)</code>
|-
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
| Ändern || <code>qUpd := qSqlInit(oDB, 'TAB')</code>, <code>qUpd.qSet('sys_uid', cUid)</code>, weitere <code>qSet</code>, <code>qUpd.SaveData(UPDATE_RECORD)</code> auswerten, <code>qSqlFree(qUpd)</code>
|-
|-
| serverTime || Serverzeit ISO-8601 mit Offset
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| 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_&lt;name&gt; || Beliebiger Custom-Claim, z.B. _OBS_JWT_CLAIM_tenant, _OBS_JWT_CLAIM_roles. Im Folge-Skript lesbar als oParams.Values['_OBS_JWT_CLAIM_&lt;name&gt;'].
|-
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
| Existenz prüfen || <code>DB_LSeek(oDB, 'TAB', cWhere)</code>
|-
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
| Werte einsetzen (Pflicht) || <code>DB_SQLVal(wert)</code>
|}
|}


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'':
=== Ändern: qSqlInit statt qSqlRead ===
 
Zum '''Ändern''' eines Satzes nehmen Sie ebenfalls <code>qSqlInit</code>. Die <code>sys_uid</code> adressiert den Satz:
{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}
 
{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''_OBS_JWT_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 ''oParams.Values['_OBS_JWT_ID']'' bereit,
falls das Skript es für eigene Protokollierung braucht.
 
<syntaxhighlight lang="pascal" line>
function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes : TJSONObject;
    cUser: string;
begin
    oRes := TJSONObject.Create();
    try
        cUser := oParams.Values['_OBS_JWT_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
            oRes.AddPair('status', 9);
            oRes.AddPair('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
            result := oRes.ToJSON();
            exit;
        end;
 
        // Rolle und Mandant neu lesen, nicht aus dem alten Token uebernehmen -
        // sonst wirkt ein Rechteentzug erst beim naechsten Login.
        oRes.AddPair('status'              , 1);
        oRes.AddPair('_OBS_JWT_ID'          , cUser);
        oRes.AddPair('_OBS_JWT_SUBJECT'    , cUser);
        oRes.AddPair('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
        oRes.AddPair('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser));
        oRes.AddPair('_OBS_JWT_REFRESH_ID'  , GlobalUID());  // loest das neue Refresh-Token aus
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
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 setzt dort ''_OBS_JWT_REVOKE''. Dasselbe gilt für
"auf allen Geräten abmelden", weil das eine Berechtigungsentscheidung braucht:
 
<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
    oRes := TJSONObject.Create();
    try
        GeraeteRegistrierungLoeschen(oParams.Values['_OBS_JWT_SUBJECT']);
 
        // 'session' = diese Sitzung, 'all' = alle Sitzungen des Subjects
        oRes.AddPair('_OBS_JWT_REVOKE' , 'session');
        oRes.AddPair('_OBS_HTTP_STATUS', 204);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
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.
<syntaxhighlight lang="delphi">
 
qUpd := qSqlInit(oDB, 'TICKETS');
Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
qUpd.qSet('sys_uid' , cUid);     // adressiert den vorhandenen Satz
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
qUpd.qSet('ti_status', '9');
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].
Speichern(qUpd, UPDATE_RECORD, 'Ticket');   // siehe Schreibfehler erkennen
 
Will das Skript einen spezifischen Fehler an den Konsumenten zurückgeben, sollte es
'''dasselbe Format und einen passenden Statuscode''' verwenden:
 
<syntaxhighlight lang="pascal" line>
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes, oErr: TJSONObject;
begin
    oRes := TJSONObject.Create();
    try
        if (Empty(oParams.Values['kundennr'])) then begin
            oErr := TJSONObject.Create();
            oErr.AddPair('code'   , 'VALIDATION_FAILED');
            oErr.AddPair('message', 'Parameter ''kundennr'' fehlt');
            oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);
 
            oRes.AddPair('_OBS_HTTP_STATUS', 422);
            oRes.AddPair('error', oErr);
            result := oRes.ToJSON();
            exit;
        end;
        // ...
    finally
        MyFreeAndNil(oRes);
    end;
end;
</syntaxhighlight>
</syntaxhighlight>


{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
<code>qSqlRead</code> ist dafür die falsche Wahl:
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
* Es liest zuerst den kompletten Satz. Das kostet einen zusätzlichen Zugriff.
Body auszuwerten - und nur so gibt der Server einen belegten
* Es schreibt nur Änderungen. Ist der neue Wert gleich dem alten, liefert <code>SaveData</code> ''False'', genau wie bei einem echten Fehler.
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}


===Ändern: qSqlInit statt qSqlRead===
{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen''' Satz an. Setzen Sie die <code>sys_uid</code> bei jeder Änderung.}}


Zum '''Ändern''' eines vorhandenen Satzes wird ebenfalls <code>qSqlInit</code>
Eine einzige Abfrage auf die <code>sys_uid</code> liefert Existenzprüfung und Schreibziel zugleich:
benutzt - der Satz wird über <code>sys_uid</code> adressiert:


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


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


===Mehrere Felder sind EIN Schreibvorgang===
=== Mehrere Felder sind ein Schreibvorgang ===
Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> an und schreibt sie mit '''einem''' <code>SaveData</code>. Felder derselben Zeile gehören in dasselbe Objekt:


Ein <code>qSqlInit</code>-Objekt nimmt beliebig viele <code>qSet</code> entgegen
<syntaxhighlight lang="delphi">
und schreibt sie mit '''einem''' <code>SaveData</code>. Fallen an derselben
// FALSCH: je Feld ein Aufruf mit eigener Abfrage und eigenem Schreibvorgang
Zeile mehrere Felder an, gehören sie in dasselbe Objekt:
FeldSetzen(cUid, 'ti_status', '9');
 
FeldSetzen(cUid, 'ti_grund' , cGrund);
<syntaxhighlight lang="pascal" line>
FeldSetzen(cUid, 'ti_von'   , cBenutzer);
// 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
// RICHTIG: ein Schreibobjekt, ein SaveData
q := qSqlInit(oDB, 'tickets');
qUpd := qSqlInit(oDB, 'TICKETS');
q.qSet('sys_uid'  , cUid);
qUpd.qSet('sys_uid'  , cUid);
q.qSet('ti_status', '9');
qUpd.qSet('ti_status', '9');
q.qSet('ti_grund' , cGrund);
qUpd.qSet('ti_grund' , cGrund);
q.qSet('ti_von'  , cBenutzer);
qUpd.qSet('ti_von'  , cBenutzer);
if (not q.SaveData(UPDATE_RECORD)) then begin
Speichern(qUpd, UPDATE_RECORD, 'Ticket');
    // ... Fehler behandeln
end;
qSqlFree(q);
</syntaxhighlight>
</syntaxhighlight>


Das ist nicht nur eine Frage der Geschwindigkeit: einzeln geschriebene Felder
Einzeln geschriebene Felder kosten je Feld eine Abfrage und einen Schreibvorgang. Wird nichts gesetzt, geben Sie das Schreibobjekt mit <code>qSqlFree</code> frei, statt ein leeres <code>SaveData</code> abzusetzen.
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===
=== 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:
* Werte aus einer 1:1-Beziehung über einen <code>LEFT JOIN</code> mitnehmen. Bei einem eindeutigen Index auf dem Join-Feld vervielfacht er die Zeilen nicht.
* Einzelwerte aus einer 1:n-Beziehung über eine Unterabfrage in der SELECT-Liste holen, nicht über einen Join.
* Eine echte Unterliste (Positionen, Dateien) nur nachladen, wenn ein Zählfeld in der Hauptabfrage sagt, dass es eine gibt.


'''<code>SaveData</code> liefert einen Boolean - und der ist die einzige
{{Hinweis|Ein GET soll lesen. Schreibvorgänge im Lesepfad vervielfachen sich mit der Zeilenzahl und laufen ohne Transaktion.}}
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,
=== Schreibfehler erkennen ===
* steht '''nichts''' in ''RESTSRV_PROTO'',
<code>SaveData</code> liefert einen Boolean, und der ist die einzige Fehlermeldung. Auch der Parameter ist ein Boolean: <code>NEW_RECORD</code> und <code>UPDATE_RECORD</code> sind Wahrheitswerte. Scheitert das Schreiben in der Datenbank (doppelter Wert in einem eindeutigen Index, zu langer Wert, fehlende Spalte), dann
* läuft das Skript weiter und antwortet mit dem Erfolg, den es selbst formuliert.
* löst das '''keine''' Exception aus,
* steht '''nichts''' in <code>RESTSRV_PROTO</code>,
* läuft das Skript weiter und meldet den Erfolg, den es selbst schreibt.


Wer den Aufruf als Anweisung schreibt, baut damit einen stillen Datenverlust ein.
Prüfen Sie den Rückgabewert deshalb immer. Am einfachsten über eine kleine Prozedur in der gemeinsamen Bibliothek:
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>
<syntaxhighlight lang="delphi">
procedure Speichern(q: TqSQL; lNeu: Boolean; const cWas: string);
procedure Speichern(qUpd: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
var lOk: Boolean;
begin
begin
     lOk := q.SaveData(lNeu);
     lOk := qUpd.SaveData(lNeu);
     qSqlFree(q);                    // auch im Fehlerfall freigeben
     qSqlFree(qUpd);                    // auch im Fehlerfall freigeben
     if (not lOk) then begin
     if (not lOk) then begin
         raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
         raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
Zeile 833: Zeile 498:
end;
end;


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


Die Exception fängt der Server: er schreibt ''Schreiben fehlgeschlagen: Ticket''
Die Exception fängt der Server. Er schreibt den Text ins Protokoll, rollt alle Änderungen der Anfrage zurück und antwortet mit '''500'''. Der <code>Idempotency-Key</code> wird frei, der Client kann wiederholen.
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==
== Anmeldeskript (JWT) ==
Zugänge mit '''JWT-Authentifizierung''' haben ein eigenes Anmeldeskript. Sie bearbeiten es in der Zugänge-Liste mit {{F7}}. Es enthält die Methoden <code>Authenticate</code> und <code>Refresh</code> mit derselben Signatur wie ein Endpunkt-Skript. Rückgabefelder, Beispiel und Fehlerfälle stehen unter [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Das Anmeldeskript|Anmeldung mit JWT]].


Wird Logik in mehreren Endpunkten gebraucht - Berechtigungsprüfungen,
== Gemeinsamen Code auslagern ==
JSON-Bausteine, Hilfsfunktionen -, muss sie nicht in jedes Skript kopiert werden.
Logik, die mehrere Endpunkte brauchen, muss nicht in jedes Skript kopiert werden. Eine Direktive lädt beim Übersetzen einen Textbaustein aus einer Tabelle nach:
Die Skript-Engine lädt Textbausteine beim Laden aus einer beliebigen Tabelle nach:


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


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


Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Der
Die Direktive steht üblicherweise direkt unter dem Kopfkommentar des Skripts. Eine Funktion aus der Bibliothek rufen Sie danach auf wie eine im Skript selbst geschriebene.
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===
=== Bibliothek als eigener Endpunkt ===
Am wenigsten Verwaltung macht eine Bibliothek als eigener Endpunkt:
# Legen Sie einen Endpunkt mit eigenem '''Pfad-Template''' an, z.B. <code>/meinapp/lib</code>.
# Schreiben Sie den Quelltext der Bibliothek in das Skript dieses Endpunkts.
# Vergeben Sie für diesen Endpunkt '''keine''' Berechtigung. Ein Aufruf von außen endet dann mit '''403'''.
# Fügen Sie in jedem nutzenden Skript die Direktive ein.


Am wenigsten Verwaltung macht es, die Lib '''als eigene Zeile in
Eine Änderung an der Bibliothek gilt für alle Skripte, die sie einbinden.
RESTSRV_ENDPOINTS''' abzulegen:


# Endpunkt anlegen mit einem eigenen Pfad-Template, z.B. <code>/meinapp/lib</code>.
{{Hinweis|Spielen Sie Bibliothek und Skripte gemeinsam ein. Nutzt ein Skript eine neue Funktion, die in der Bibliothek noch fehlt, meldet der Übersetzer nur den neuen Namen als ''Unknown name''. Das sieht leicht wie ein Fehler im Skript aus.}}
# 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
== Verfügbare Bibliotheken ==
wirkt auf alle einbindenden Endpunkte, ohne dass ein einziges Endpunkt-Skript
Im Skript stehen die OBS-Funktionen bereit, die Sie aus Makros kennen:
angefasst werden muss.
* Zeichenketten, Datum, Zahlen und Konstanten wie <code>CRLF</code>, <code>SINGELQUOTE</code> und <code>MINDATETIME</code>
* Datenbank: lesen, schreiben, direkt ausführen
* Dateifunktionen
* Fachfunktionen, z.B. zu Aufträgen, Reparaturaufträgen, Angeboten, Einkauf und Artikelbewegungen
* Reader, Writer und die [[#Zeitangaben|Zeitfunktionen]] dieser Seite


{{Hinweis|'''Lib und Skripte gemeinsam einspielen.''' Kommt in der Lib eine neue
Eine JSON-Bibliothek braucht ein Endpunkt-Skript nicht. Der Reader liest den Körper, der Writer erzeugt die Antwort.
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.}}
 
==Fallstricke im Skript==
 
Die folgenden Punkte unterscheiden das Skript von normalem Delphi-Code und kosten
sonst eine Runde Fehlersuche:


== Fallstricke im Skript ==
{| class="wikitable"
{| class="wikitable"
! Stolperstein !! Richtig
! 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''
| Datenbankfunktion mit zusätzlicher Kennung als erstem Parameter, wie im Delphi-Code || Im Skript ohne Kennung: <code>DB_SOpen(oDB, cSql, qDat)</code>, <code>qSqlInit(oDB, 'TAB')</code>, <code>qSqlRead(oDB, 'TAB', cWhere)</code>
|-
|-
| ''oBody.TryGetValue&lt;T&gt;(…)'' || Generics gibt es nicht - über ''GetValue'' lesen (siehe oBody)
| Generics, z.B. <code>oReader.Str&lt;T&gt;(…)</code> || Gibt es in der Skriptsprache nicht. Je Typ ein eigener Leser: <code>Str</code>, <code>Int</code>, <code>Num</code>, <code>Bool</code>.
|-
|-
| ''EMPTY_DATE'' für ein leeres Datum || ''EMPTY_DATE'' ist im Skript ein '''String'''. Für Datumsvariablen und -vergleiche '''MINDATETIME''' verwenden
| Hilfsfunktion, die ein JSON-Fragment als Zeichenkette zurückgibt || Den Writer als Parameter übergeben und an der richtigen Stelle hineinschreiben
|-
|-
| ''fVal'' auf einen JSON-Zahlenwert || JSON liefert den Dezimalpunkt, ''fVal'' erwartet die lokale Notation: vorher <code>StrTran(cVal, '.', ',')</code>
| <code>oWriter.ArrEnd</code> nach <code>RootArr</code> || <code>RootArr</code> öffnet keine Ebene. Ein <code>ArrEnd</code> dazu ist ein Strukturfehler.
|-
|-
| ''TStringList'' für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen über einen Delimiter-String führen (<code>'&#124;' + wert + '&#124;'</code>) und mit ''Pos'' prüfen
| Zahlen selbst formatieren, z.B. mit <code>NStr</code> || <code>NStr</code> liefert deutsche Schreibweise mit Tausenderpunkt. Für JSON <code>oWriter.Num('preis', nWert, 2)</code> verwenden.
|-
|-
| Default-Parameter in eigenen Funktionen || Werden nicht unterstützt - alle Parameter ausschreiben
| <code>fVal</code> auf eine JSON-Zahl || <code>oReader.Num</code> bzw. <code>oReader.NumDef</code> verwenden. Sie lesen den Dezimalpunkt richtig.
|-
|-
| <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]]
| <code>EMPTY_DATE</code> für ein leeres Datum || <code>EMPTY_DATE</code> ist im Skript eine Zeichenkette. Für Datumsvariablen und Vergleiche <code>MINDATETIME</code> verwenden.
|-
|-
| 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]]
| <code>TStringList</code> für Zwischenlisten || In Skripten unzuverlässig. Kleine Mengen als Zeichenkette mit Trennzeichen führen (<code>'&#124;' + wert + '&#124;'</code>) und mit <code>Pos</code> prüfen.
|-
|-
| 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]]
| Vorgabewerte für Parameter eigener Funktionen || Werden nicht unterstützt. Alle Parameter ausschreiben.
|-
|-
| 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
| <code>qUpd.SaveData(…)</code> als Anweisung ohne Auswertung || Rückgabewert immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
|-
| Je Feld ein eigener Aufruf zum Setzen || Ein <code>qSqlInit</code>-Objekt, alle <code>qSet</code>, ein <code>SaveData</code>, siehe [[#Mehrere Felder sind ein Schreibvorgang|Mehrere Felder]]
|-
| Ein Wert je Zeile nachgeschlagen || <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n), siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
| Ausgabeparameter vom Typ <code>var … : TDateTime</code> || Bringt die Skriptausführung zum Absturz, und zwar erst beim Lesen des Werts. <code>var string</code>, <code>var Integer</code> und <code>var Double</code> laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und beim Aufrufer wandeln.
|}
|}


==Skript-Cache==
== Skript-Cache ==
Der Server hält die Endpunkte samt Skript bis zu 60 Sekunden im Zwischenspeicher. Eine Änderung am Skript wirkt deshalb spätestens nach 60 Sekunden. Nach einem Neustart des Dienstes wirkt sie sofort.


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.
== Beispiel ==
Ein Endpunkt mit dem '''Pfad-Template''' <code>/beispiel/tickets/{nr}</code> liest ein Ticket und ändert seinen Status. Tabelle und Felder stehen für Ihre eigenen; <code>Speichern</code> ist die Prozedur aus [[#Schreibfehler erkennen|Schreibfehler erkennen]].


==Verfügbare Bibliotheken==
<syntaxhighlight lang="delphi">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
    qTick: TxFQuery;
    lGef : Boolean;
begin
    cSql := 'SELECT ti_nr, ti_betreff, ti_status FROM TICKETS' +
            ' WHERE ti_nr = ' + DB_SQLVal(oReader.Path('nr'));


Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:
    lGef := false;
    if (DB_SOpen(oDB, cSql, qTick)) then begin
        if (not qTick.EoF) then begin
            lGef := true;
            oWriter.Str('nr'    , AllTrim(qTick.A2C('ti_nr')));
            oWriter.Str('betreff', AllTrim(qTick.A2C('ti_betreff')));
            oWriter.Str('status' , AllTrim(qTick.A2C('ti_status')));
        end;
    end;
    DB_Close(qTick);


* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
    if (not lGef) then begin
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
* ''Base.qSqlReg'' - Schreibzugriffe
    end;
* ''System.JSON'' - JSON-Objekte und -Arrays
end;
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''MINDATETIME''


Die wichtigsten Aufrufe mit ihren Skript-Signaturen:
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cNr    : string;
    cStatus: string;
    cUid  : string;
    cSql  : string;
    qTick  : TxFQuery;
    qUpd  : TqSQL;
begin
    cNr    := oReader.Path('nr');
    cStatus := '';
    if (not oReader.Str('status', cStatus)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
        exit;
    end;


{| class="wikitable"
    cUid := '';
! Zweck !! Aufruf
    cSql := 'SELECT sys_uid FROM TICKETS WHERE ti_nr = ' + DB_SQLVal(cNr);
|-
    if (DB_SOpen(oDB, cSql, qTick)) then begin
| 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>
        if (not qTick.EoF) then begin
|-
            cUid := qTick.A2UID();
| 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]]
        end;
|-
    end;
| Ä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]]
    DB_Close(qTick);
|-
 
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
    if (Empty(cUid)) then begin
|-
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
| Existenzprüfung || <code>DB_LSeek(oDB, 'tab', cWhere)</code>
        exit;
|-
    end;
| Werte quoten (Pflicht) || <code>DB_SQLVal(wert)</code>
 
|}
    qUpd := qSqlInit(oDB, 'TICKETS');
    qUpd.qSet('sys_uid' , cUid);
    qUpd.qSet('ti_status', cStatus);
    Speichern(qUpd, UPDATE_RECORD, 'Ticket');
 
    oWriter.Str('nr'   , cNr);
    oWriter.Str('status', cStatus);
end;
</syntaxhighlight>
 
Aufruf des PUT mit curl:


{{Hinweis|Alle diese Funktionen beginnen im Skript mit ''oDB''. Ein zusätzlicher
<syntaxhighlight lang="bash">
AD-UID-Parameter als erstes Argument gehört zur Delphi-Variante und lässt sich im
curl -X PUT "https://obs.example.com:8443/beispiel/tickets/4711" \
Skript nicht übersetzen.}}
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
  -H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"status": "9"}'
</syntaxhighlight>


Konkrete Beispiele:
Weitere vollständige Beispiele:
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Daten-Abruf mit JWT-Anmeldung|Beispiel 1: Daten-Abruf mit JWT]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper|Beispiel 3: Datensatz anlegen mit JSON-Body]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Beispiel 6: Datei-Upload und Ablage]]


* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel1|Beispiel 1: Daten-Abruf mit JWT]]
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel 2: Zeiterfassung als komplette Webanwendung]]
* [[OBS/Kostenpflichtige Module/REST-Server|REST-Server]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body (CRUD)]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel 5: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6: Datei-Upload und Ablage im DMS]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]

Aktuelle Version vom 17. November 2026, 07:24 Uhr

Scripting

Hinter jedem Endpunkt steht ein Skript, das Sie selbst schreiben. Damit bestimmen Sie, welche OBS-Daten ein Endpunkt liest oder ändert und was der Client zurückbekommt. Authentifizierung, Fehlerformat, Idempotenz und Transaktion übernimmt der Server. Diese Seite beschreibt die Skript-Schnittstelle: Anfrage lesen, Antwort schreiben, Fehler melden, gemeinsamen Code nutzen.

Das Skript ist in Object Pascal geschrieben und nutzt die OBS-Funktionen für Datenbank und Hilfsfunktionen. Wie ein Client den Server aufruft, steht unter HTTP-Schnittstelle.

Aufruf

Je HTTP-Methode enthält das Skript eine gleichnamige Prozedur. Der Server ruft die Prozedur auf, die zur Methode der Anfrage 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);
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);

Ein Skript enthält nur die Methoden, die der Endpunkt anbietet. Fehlt die Methode zur Anfrage, antwortet der Server mit 405 METHOD_NOT_ALLOWED. Der Header Allow nennt die Methoden, die das Skript tatsächlich enthält:

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

Lässt sich das Skript nicht übersetzen, antwortet der Server mit 500. Die Meldung des Übersetzers mit Grund und Zeile steht im Protokoll.

Parameter

Parameter Typ Pflicht Standard Bedeutung
oReader TxRestReader ✓ – Die Anfrage: Query, Header, Pfadwerte, Formularfelder, Token-Werte, Körper und hochgeladene Datei. Siehe oReader.
oWriter TxRestWriter ✓ – Die Antwort: Felder, Statuscode, Header, Fehler oder Datei. Siehe oWriter.

Beide Objekte erzeugt und besitzt der Server. Im Skript wird nichts angelegt und nichts freigegeben. Die Datenbankverbindung steht im Skript global als oDB bereit.

Sicherheitshinweise

ACHTUNG: Endpunkt-Skripte verarbeiten Daten aus dem Internet. Bauen Sie Werte des Clients nie ungeprüft in SQL ein. Setzen Sie jeden Wert über DB_SQLVal ein und prüfen Sie Eingaben gegen erlaubte Werte.
  • Prüfen Sie Pflichtfelder, Typen und Wertebereiche.
  • Geben Sie nur zurück, was der Client braucht: keine internen Kennungen, keine Systemfelder, keine Passwörter.
  • Lesen Sie Mandant und Rollen aus dem Token, nie aus Körper oder Query.
  • Schreiben Sie keine internen Details in Fehlermeldungen. Die message geht an den Client.

Die Anfrage lesen: oReader

oReader ist der einzige Zugang zur Anfrage. Alle Werte sind Zeichenketten oder werden über einen typisierten Leser geholt.

Aufruf Liefert
oReader.Param('kundennr') Query-Parameter, Formularwert (application/x-www-form-urlencoded) oder HTTP-Header. Getrimmt, leer wenn nicht gesendet.
oReader.Path('nr') Wert eines Platzhalters aus dem Pfad-Template
oReader.Form('bemerkung') Formularfeld einer multipart/form-data-Übertragung
oReader.Subject() Subject (sub) des vorgelegten Tokens
oReader.Claim('tenant') Eigener Claim des vorgelegten Tokens, als Text
oReader.TraceId() Kennung der Anfrage, gleich dem Header X-Trace-Id der Antwort
oReader.Offset() UTC-Offset des Servers, z.B. +01:00
oReader.HasBody() Wurde ein JSON-Körper gesendet?
oReader.UploadPath(), UploadName(), UploadType(), UploadSha() Hochgeladene Datei, siehe Datei-Uploads

Was der Server vorher filtert:

  • Die Header authorization, cookie, proxy-authorization, x-forwarded-for, x-real-ip, apikey und api_key erreichen das Skript nicht.
  • Namen, die mit _OBS_ beginnen, sind dem Server vorbehalten. Header und Query-Parameter mit solchen Namen verwirft er.
  • Werte aus Header, Query, Pfad und Formular kürzt er nach 1024 Zeichen.
  • Null-Bytes und Steuerzeichen entfernt er. Tabulator, CR und LF bleiben.
cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
    // ...
end;

Der Körper

Den JSON-Körper liest oReader über Pfade. Es gibt keine Unterobjekte, keine Typumwandlung und nichts freizugeben.

Aufruf Bedeutung
oReader.Str('betreff', cWert) Liest den Wert. Rückgabe Boolean: War das Feld da? Fehlt es, bleibt die Variable unverändert.
oReader.Int('menge', nWert) dito, Ganzzahl
oReader.Num('preis', nWert) dito, Kommazahl. Den Dezimalpunkt aus JSON liest der Reader richtig.
oReader.Bool('aktiv', lWert) dito, Boolean
oReader.NumDef('rabatt', nWert, 0) wie Num, mit Vorgabewert
oReader.Has('feld') Ist das Feld vorhanden, auch mit null?
oReader.Count('zeiten') Anzahl Einträge einer Liste, 0 wenn keine Liste
oReader.IsArr('zeiten'), oReader.IsObj('zeiten[0]') Ist der Wert eine Liste bzw. ein Objekt?
oReader.Keys() Alle Feldnamen der obersten Ebene, in Kommas eingefasst

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

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;
HINWEIS: Der Rückgabewert unterscheidet „nicht gesendet“ von „leer gesendet“. Bei "feld": null liefert oReader.Str('feld', cWert) true und einen leeren Wert, bei fehlendem Feld false. So unterscheidet ein PATCH „Feld leeren“ von „Feld nicht ändern“.

Regeln für den Körper:

  • Der Server liest den Körper als UTF-8.
  • Nur ein JSON-Objekt als Wurzel gilt als Körper. Eine Liste als Wurzel oder ungültiges JSON ergibt keinen Körper: HasBody() ist false, jeder Leser liefert false. Der Server antwortet in diesem Fall nicht mit 400. Prüfen Sie Pflichtfelder deshalb im Skript.
  • Ein Körper ohne Datei darf höchstens 10 MB groß sein, auch nach dem Entpacken. Darüber antwortet der Server mit 413, das Skript läuft nicht. Gepackte Körper: HTTP-Schnittstelle.

Werte des Servers

Diese Werte setzt der Server. Ein Client kann sie nicht überschreiben.

Aufruf Inhalt
oReader.Param('_OBS_SERVER_TIME') Serverzeit nach ISO 8601 mit UTC-Offset, z.B. 2026-11-17T09:12:33+01:00
oReader.Offset() Nur der Offset daraus, z.B. +01:00. Er geht in die Zeitfunktionen.
oReader.TraceId() Kennung der Anfrage
oReader.Param('_OBS_JWT_EXP_SEC') Laufzeit des Access-Tokens in Sekunden (Lebenszeit (Min) × 60)

Bei Zugängen mit JWT-Authentifizierung stehen zusätzlich die Werte des Tokens bereit: oReader.Subject(), oReader.Claim('<name>'), oReader.Param('_OBS_JWT_ID'), oReader.Param('_OBS_JWT_AUDIENCE') sowie die Sitzungskennungen sid und rid. Die vollständige Liste steht unter Anmeldung mit JWT.

Pfad-Parameter

Enthält das Pfad-Template Platzhalter, liefert oReader.Path deren Werte:

Pfad-Template Zugriff im Skript
/beispiel/auftraege/{nr} oReader.Path('nr')
/beispiel/auftraege/{nr}/module/{code} oReader.Path('nr'), oReader.Path('code')

Der Name ist geschützt: Ein Client kann einen Pfadwert nicht über Query oder Header unterschieben. Der Wert stammt aber aus der URL des Clients. Prüfen Sie ihn wie jede andere Eingabe, z.B. ob der Auftrag zum Mandanten im Token gehört. Ein vollständiges Beispiel zeigt Beispiel 4.

Datei-Uploads

Hat der Endpunkt den Haken Datei-Upload, nimmt der Server Dateien entgegen und legt sie in einem temporären Verzeichnis ab. Das Skript erhält die Datei über diese Aufrufe:

Aufruf Inhalt
oReader.UploadPath() Vollständiger Pfad der temporären Datei auf dem Server
oReader.UploadName() Originaler Dateiname
oReader.UploadType() Content-Type der Datei, kleingeschrieben. Ohne Angabe des Clients application/octet-stream.
oReader.UploadSha() SHA-256 der gespeicherten Datei, hexadezimal in Kleinbuchstaben. Vergleichen Sie damit eine Prüfsumme, die der Client mitsendet.
  • Beide Übertragungswege liefern dieselben Werte: multipart/form-data und der fortsetzbare Upload mit Content-Range. Beim fortsetzbaren Upload läuft das Skript erst, wenn die Datei vollständig ist.
  • Ohne Dateinamen weist der Server den Upload mit 400 ab, das Skript läuft nicht. UploadPath() und UploadName() sind im Skript also immer gefüllt.
  • Ein Upload-Körper wird nicht als JSON gelesen. HasBody() ist false.
  • Zusatzangaben eines Formulars liest das Skript mit oReader.Form('<name>'). Das sind die Partien ohne filename=. Vom Namen bleiben nur Buchstaben, Ziffern und Unterstrich, höchstens 40 Zeichen.
  • Beim fortsetzbaren Upload gibt es keine Formularfelder. Zusatzangaben kommen dort über Query-Parameter oder Header.
  • Ein Upload an einen Endpunkt ohne Datei-Upload beantwortet der Server mit 415. Überschreitet die Übertragung die maximale Dateigröße (MB) des Endpunkts, antwortet er mit 413.
HINWEIS: Der Server verschiebt die temporäre Datei nicht. Das Skript übernimmt sie an ihren Zielort.

Übertragung, Header und Statuscodes: Datei-Upload. Ein vollständiges Beispiel zeigt Beispiel 6.

Die Antwort schreiben: oWriter

Der Writer schreibt der Reihe nach: Jeder Aufruf hängt ein Feld an der Stelle an, an der er steht. Die äußere Klammer setzt der Server. Schreibt das Skript nichts, lautet die Antwort {}. Ohne weitere Angabe ist der Status 200 und der Content-Type application/json; charset=utf-8.

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
    oWriter.Str('wert_string', '123');
    oWriter.Int('wert_int'   , 456);
end;
Aufruf Ergebnis
oWriter.Str('name', cWert) Zeichenkette, immer maskiert
oWriter.StrN('name', cWert) wie Str, aber null statt einer leeren Zeichenkette
oWriter.Int('anz', nWert) Ganzzahl
oWriter.Num('preis', nWert, 2) Kommazahl mit fester Stellenzahl. Immer mit Dezimalpunkt, unabhängig von den Ländereinstellungen des Servers.
oWriter.Bool('aktiv', lWert) true oder false
oWriter.Null('lat') ausdrücklich null
oWriter.ObjBegin('kunde') … oWriter.ObjEnd Unterobjekt
oWriter.ArrBegin('dateien') … oWriter.ArrEnd Liste
oWriter.RootArr() Die Wurzel ist eine Liste statt eines Objekts. Steht vor dem ersten Feld. Ein ArrEnd gehört nicht dazu.
oWriter.Raw('meta', cJson) Fertiges JSON-Fragment einbetten, siehe unten

In einer Liste hat ein Eintrag keinen Namen. Der leere Feldname steht dafür:

oWriter.ArrBegin('dateien');
while (not qDat.EoF) do begin
    oWriter.ObjBegin('');
    oWriter.Str ('uid'      , qDat.A2C('f_uid'));
    oWriter.Int ('bytes'    , qDat.A2I('f_bytes'));
    oWriter.StrN('kategorie', AllTrim(qDat.A2C('f_kat')));   // null, wenn leer
    oWriter.ObjEnd;
    qDat.Next();
end;
oWriter.ArrEnd;

Ein Name in einer Liste, ein fehlender Name in einem Objekt und eine Ebene, die am Ende der Methode noch offen ist, sind Strukturfehler. Der Server antwortet dann mit 500 und nennt die Stelle im Protokoll. Halbes JSON liefert er nie aus.

HINWEIS: Eine Hilfsprozedur bekommt den Writer als Parameter und schreibt an der Stelle, an der sie aufgerufen wird. Sie gibt kein Fragment zurück. So steht die Reihenfolge der Antwort im Code: procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);

Raw prüft das Fragment und bettet den Originaltext ein. Ungültiges JSON führt zu einem Serverfehler, der das Feld nennt. Gebraucht wird Raw für gespeicherte, signierte Dokumente: Neu aufgebaut, verlöre das Dokument die signierte Reihenfolge der Felder.

Zeitangaben

Zeitpunkte gehen als ISO 8601 mit Offset über die Leitung. Für die Umwandlung gibt es eigene Funktionen:

Aufruf Zweck
RestIsoFromDate(dWert, cOffset) OBS-Zeitpunkt in 2026-09-09T14:12:00+02:00. Leere Zeichenkette bei leerem Datum.
RestDateFromIso(cWert, cOffset) ISO-Zeichenkette in einen OBS-Zeitpunkt in Ortszeit des Servers
oReader.Offset() Der Offset für beide Funktionen
RestOffsetToMinutes(cOffset) Offset in Minuten, für eigene Rechnungen

Antwort steuern: Statuscode, Header, traceId

Statuscode, Header, Fehler und Dateien setzen eigene Aufrufe des Writers, nicht Felder im Körper.

Aufruf Wirkung
oWriter.Status(201) HTTP-Statuscode, z.B. 201, 204, 409 oder 422. Ohne Angabe: 200. Werte außerhalb von 100 bis 599 ignoriert der Server.
oWriter.Header('ETag', '"7"') Beliebiger Header der Antwort, z.B. ETag, Location, Retry-After. Steuerzeichen in Name und Wert entfernt der Server.
oWriter.NoBody() Kein Körper, für 204
oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt') Fertige Fehlerantwort im Format des Servers, siehe Fehlerbehandlung
oWriter.HasError() Steht schon eine Fehlerantwort im Writer?
oWriter.JwtRevoke('session') Sperrt die Sitzung des vorgelegten Tokens, mit 'all' alle Sitzungen des Subjects. Siehe Anmeldung mit JWT.
oWriter.SendFile(cPfad, cName, cTyp) Eine Datei statt eines JSON-Körpers ausliefern. Die Datei bleibt liegen, der Download ist fortsetzbar.
oWriter.SendTempFile(cPfad, cName, cTyp) Wie SendFile, die Datei wird nach dem Senden gelöscht. Für Ergebnisse, die je Abruf entstehen.

Dateiantworten beschreibt Datei-Download.

Jede Antwort trägt den Header X-Trace-Id. Dieselbe Kennung liefert oReader.TraceId(), und sie steht in jeder Fehlerzeile des Protokolls. So findet der Betreiber einen Fehler ohne Zugriff auf das Gerät.

Setzt das Skript den Header Content-Encoding selbst, packt der Server die Antwort nicht noch einmal.

Beispiel: Anlegen mit 201, Location und ETag

procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueNr: string;
begin
    // ... Datensatz anlegen, neue Nummer ermitteln ...

    oWriter.Str('nr', cNeueNr);
    oWriter.Status(201);
    oWriter.Header('Location', '/beispiel/tickets/' + cNeueNr);
    oWriter.Header('ETag'    , '"1"');
end;

Beispiel: Versionsprüfung mit ETag und If-Match

Mit Statuscode, Header und dem Header If-Match der Anfrage führt das Skript je Datensatz einen Versionszähler. Veraltete Schreibzugriffe lehnt es mit 409 ab. Clients senden den ETag meist in Anführungszeichen ("7"), manche ohne.

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var nAktuell: Integer;
    cETag   : string;
    cIfMatch: string;
begin
    nAktuell := TicketVersion(oReader.Path('nr'));   // eigene Funktion
    cETag    := '"' + IntToStr(nAktuell) + '"';
    cIfMatch := AllTrim(oReader.Param('if-match'));

    if (cIfMatch <> cETag) and (cIfMatch <> IntToStr(nAktuell)) then begin
        // Der gültige ETag gehört auch an die Ablehnung,
        // sonst scheitert der nächste Versuch des Clients wieder.
        oWriter.Header('ETag', cETag);
        oWriter.Error(409, 'VERSION_CONFLICT', 'Der Datensatz wurde zwischenzeitlich geändert');
        exit;
    end;

    // ... speichern, Version hochzählen ...
    oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
end;

VERSION_CONFLICT ist hier ein eigener Code des Skripts. Der Server selbst verwendet für 409 den Code CONFLICT.

Transaktion

POST, PUT, PATCH und DELETE laufen in einer Datenbanktransaktion. Darin liegen alle Schreibvorgänge des Skripts und das Ergebnis der Idempotenz-Prüfung.

Ende des Skripts Wirkung
Status unter 400 Alle Änderungen werden festgeschrieben.
Status 400 oder höher Alle Änderungen werden zurückgerollt.
Exception oder Skriptfehler Alle Änderungen werden zurückgerollt, der Client erhält 500.
  • Ablehnen ist gefahrlos. Ein Skript darf schreiben und danach mit oWriter.Error abbrechen. In der Datenbank bleibt nichts davon.
  • Auch eigene Protokollzeilen, die das Skript in eine Tabelle schreibt, werden bei Status 400 oder höher zurückgerollt. Die Fehlerzeile des Servers in RESTSRV_PROTO bleibt, siehe Fehler im Protokoll.
  • Eigene Transaktionen im Skript (StartTransaction, Commit) sind wirkungslos. Sie liegen innerhalb der Transaktion des Servers, und nur deren Ende zählt.
  • Teilweise Schreibvorgänge bleiben nur stehen, wenn das Skript einen Schreibfehler übergeht und mit Status unter 400 antwortet. Werten Sie deshalb jeden Schreibvorgang aus, siehe Schreibfehler erkennen.

GET läuft ohne Transaktion. Schreibt ein GET-Skript, wirkt jeder Schreibvorgang sofort und bleibt auch bei einer Fehlerantwort stehen.

Idempotenz

Bei POST, PUT, PATCH und DELETE fängt der Server doppelte Sendungen über den Header Idempotency-Key ab. Das Skript braucht dafür keine eigene Logik. Fehlt der Header, läuft das Skript nicht.

Für das Skript gilt:

  • Eine Wiederholung mit gespeicherter Antwort beantwortet der Server selbst. Das Skript läuft dabei nicht.
  • Gespeichert wird nur eine Antwort mit Status 2xx ohne Datei. Was sie enthält, ist eingefroren. Schreiben Sie die Antwort deshalb vollständig.
  • Melden Sie fachliche Ablehnungen mit 4xx (z.B. 404, 409, 422), nicht mit 200 und Fehlertext. Eine 2xx-Antwort würde gespeichert, und der Client bekäme sie bei jedem weiteren Versuch erneut.
  • Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos.

Den Ablauf aus Sicht des Clients beschreibt HTTP-Schnittstelle.

Fehlerbehandlung im Skript

Löst das Skript eine Exception aus oder lässt es sich nicht übersetzen, antwortet der Server mit 500 INTERNAL_ERROR und einer allgemeinen Meldung. Den Fehlertext schreibt er ins Protokoll. Der Client sieht keine internen Details.

Für einen gezielten Fehler gibt es einen Aufruf. Er erzeugt dieselbe Fehlerantwort wie die Fehler des Servers: Statuscode, code, message, uid und traceId.

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;
HINWEIS: Error verwirft einen schon begonnenen Körper und setzt die Fehlerantwort. Ein Skript darf also Felder schreiben und danach noch abbrechen. Nur eine noch offene Ebene (ObjBegin ohne ObjEnd) bleibt ein Strukturfehler.

Codes, die auch der Server verwendet: VALIDATION_FAILED (422), NOT_FOUND (404), FORBIDDEN_ROLE (403), CONFLICT (409). Eigene, fachlich sprechende Codes sind erlaubt. Halten Sie sie stabil, denn Clients richten ihre Reaktion danach aus. Alle Codes des Servers: HTTP-Schnittstelle.

Fehler im Protokoll

Jede Antwort des Skripts mit Status 400 oder höher schreibt der Server als eine Zeile nach RESTSRV_PROTO, mit code und message aus dem Fehlerobjekt:

Fehler VALIDATION_FAILED [422 POST /beispiel/tickets] [trace=<traceId>]: Parameter "kundennr" fehlt

Daraus folgt:

  • Verwenden Sie oWriter.Error. Ohne Fehlerobjekt steht im Protokoll nur der Code aus dem Status und der Text „Antwort ohne error-Objekt“.
  • Schreiben Sie keine sensiblen Daten in die message. Sie steht im Protokoll und geht an den Client.
  • Schreiben Sie für dieselbe Ablehnung keine eigene Protokollzeile. Der Server hat sie bereits.

Protokoll und Suche über die traceId: Betrieb und Fehlersuche.

Datenbankzugriff

Im Skript beginnt jede Datenbankfunktion mit oDB, ohne weiteren Parameter davor. Der Abfragetyp für DB_SOpen ist TxFQuery.

Zweck Aufruf
Lesen DB_SOpen(oDB, cSql, qDat), dann qDat.EoF, qDat.Next(), qDat.A2C('feld'), A2I, A2F, A2D, A2UID(), am Ende DB_Close(qDat)
Neu anlegen qUpd := qSqlInit(oDB, 'TAB'), qUpd.qSet('feld', wert), qUpd.SaveData(NEW_RECORD) auswerten, qSqlFree(qUpd)
Ändern qUpd := qSqlInit(oDB, 'TAB'), qUpd.qSet('sys_uid', cUid), weitere qSet, qUpd.SaveData(UPDATE_RECORD) auswerten, qSqlFree(qUpd)
Direkt ausführen DB_SqlExec(oDB, cSql)
Existenz prüfen DB_LSeek(oDB, 'TAB', cWhere)
Werte einsetzen (Pflicht) DB_SQLVal(wert)

Ändern: qSqlInit statt qSqlRead

Zum Ändern eines Satzes nehmen Sie ebenfalls qSqlInit. Die sys_uid adressiert den Satz:

qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('sys_uid'  , cUid);      // adressiert den vorhandenen Satz
qUpd.qSet('ti_status', '9');
Speichern(qUpd, UPDATE_RECORD, 'Ticket');   // siehe Schreibfehler erkennen

qSqlRead ist dafür die falsche Wahl:

  • Es liest zuerst den kompletten Satz. Das kostet einen zusätzlichen Zugriff.
  • Es schreibt nur Änderungen. Ist der neue Wert gleich dem alten, liefert SaveData False, genau wie bei einem echten Fehler.
HINWEIS: Ohne sys_uid legt qSqlInit einen neuen Satz an. Setzen Sie die sys_uid bei jeder Änderung.

Eine einzige Abfrage auf die sys_uid liefert Existenzprüfung und Schreibziel zugleich:

cUid := '';
if (DB_SOpen(oDB, 'SELECT sys_uid FROM TICKETS WHERE ' + cWhere + ' LIMIT 1', qDat)) then begin
    if (not qDat.EoF) then begin
        cUid := qDat.A2UID();
    end;
end;
DB_Close(qDat);

if (not Empty(cUid)) then begin
    // ändern: qSqlInit mit sys_uid
end else begin
    // anlegen: qSqlInit ohne sys_uid
end;

Mehrere Felder sind ein Schreibvorgang

Ein qSqlInit-Objekt nimmt beliebig viele qSet an und schreibt sie mit einem SaveData. Felder derselben Zeile gehören in dasselbe Objekt:

// FALSCH: je Feld ein Aufruf mit eigener Abfrage und eigenem Schreibvorgang
FeldSetzen(cUid, 'ti_status', '9');
FeldSetzen(cUid, 'ti_grund' , cGrund);
FeldSetzen(cUid, 'ti_von'   , cBenutzer);

// RICHTIG: ein Schreibobjekt, ein SaveData
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('sys_uid'  , cUid);
qUpd.qSet('ti_status', '9');
qUpd.qSet('ti_grund' , cGrund);
qUpd.qSet('ti_von'   , cBenutzer);
Speichern(qUpd, UPDATE_RECORD, 'Ticket');

Einzeln geschriebene Felder kosten je Feld eine Abfrage und einen Schreibvorgang. Wird nichts gesetzt, geben Sie das Schreibobjekt mit qSqlFree frei, statt ein leeres SaveData abzusetzen.

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:

  • Werte aus einer 1:1-Beziehung über einen LEFT JOIN mitnehmen. Bei einem eindeutigen Index auf dem Join-Feld vervielfacht er die Zeilen nicht.
  • Einzelwerte aus einer 1:n-Beziehung über eine Unterabfrage in der SELECT-Liste holen, nicht über einen Join.
  • Eine echte Unterliste (Positionen, Dateien) nur nachladen, wenn ein Zählfeld in der Hauptabfrage sagt, dass es eine gibt.
HINWEIS: Ein GET soll lesen. Schreibvorgänge im Lesepfad vervielfachen sich mit der Zeilenzahl und laufen ohne Transaktion.

Schreibfehler erkennen

SaveData liefert einen Boolean, und der ist die einzige Fehlermeldung. Auch der Parameter ist ein Boolean: NEW_RECORD und UPDATE_RECORD sind Wahrheitswerte. Scheitert das Schreiben in der Datenbank (doppelter Wert in einem eindeutigen Index, zu langer Wert, fehlende Spalte), dann

  • löst das keine Exception aus,
  • steht nichts in RESTSRV_PROTO,
  • läuft das Skript weiter und meldet den Erfolg, den es selbst schreibt.

Prüfen Sie den Rückgabewert deshalb immer. Am einfachsten über eine kleine Prozedur in der gemeinsamen Bibliothek:

procedure Speichern(qUpd: TqSQL; lNeu: Boolean; const cWas: string);
var lOk: Boolean;
begin
    lOk := qUpd.SaveData(lNeu);
    qSqlFree(qUpd);                     // auch im Fehlerfall freigeben
    if (not lOk) then begin
        raise Exception.Create('Schreiben fehlgeschlagen: ' + cWas);
    end;
end;

// Aufruf statt SaveData und qSqlFree:
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('ti_betreff', cBetreff);
Speichern(qUpd, NEW_RECORD, 'Ticket');

Die Exception fängt der Server. Er schreibt den Text ins Protokoll, rollt alle Änderungen der Anfrage zurück und antwortet mit 500. Der Idempotency-Key wird frei, der Client kann wiederholen.

Anmeldeskript (JWT)

Zugänge mit JWT-Authentifizierung haben ein eigenes Anmeldeskript. Sie bearbeiten es in der Zugänge-Liste mit F7. Es enthält die Methoden Authenticate und Refresh mit derselben Signatur wie ein Endpunkt-Skript. Rückgabefelder, Beispiel und Fehlerfälle stehen unter Anmeldung mit JWT.

Gemeinsamen Code auslagern

Logik, die mehrere Endpunkte brauchen, muss nicht in jedes Skript kopiert werden. Eine Direktive lädt beim Übersetzen einen Textbaustein aus einer Tabelle nach:

{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
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. Eine Funktion aus der Bibliothek rufen Sie danach auf wie eine im Skript selbst geschriebene.

Bibliothek als eigener Endpunkt

Am wenigsten Verwaltung macht eine Bibliothek als eigener Endpunkt:

  1. Legen Sie einen Endpunkt mit eigenem Pfad-Template an, z.B. /meinapp/lib.
  2. Schreiben Sie den Quelltext der Bibliothek in das Skript dieses Endpunkts.
  3. Vergeben Sie für diesen Endpunkt keine Berechtigung. Ein Aufruf von außen endet dann mit 403.
  4. Fügen Sie in jedem nutzenden Skript die Direktive ein.

Eine Änderung an der Bibliothek gilt für alle Skripte, die sie einbinden.

HINWEIS: Spielen Sie Bibliothek und Skripte gemeinsam ein. Nutzt ein Skript eine neue Funktion, die in der Bibliothek noch fehlt, meldet der Übersetzer nur den neuen Namen als Unknown name. Das sieht leicht wie ein Fehler im Skript aus.

Verfügbare Bibliotheken

Im Skript stehen die OBS-Funktionen bereit, die Sie aus Makros kennen:

  • Zeichenketten, Datum, Zahlen und Konstanten wie CRLF, SINGELQUOTE und MINDATETIME
  • Datenbank: lesen, schreiben, direkt ausführen
  • Dateifunktionen
  • Fachfunktionen, z.B. zu Aufträgen, Reparaturaufträgen, Angeboten, Einkauf und Artikelbewegungen
  • Reader, Writer und die Zeitfunktionen dieser Seite

Eine JSON-Bibliothek braucht ein Endpunkt-Skript nicht. Der Reader liest den Körper, der Writer erzeugt die Antwort.

Fallstricke im Skript

Stolperstein Richtig
Datenbankfunktion mit zusätzlicher Kennung als erstem Parameter, wie im Delphi-Code Im Skript ohne Kennung: DB_SOpen(oDB, cSql, qDat), qSqlInit(oDB, 'TAB'), qSqlRead(oDB, 'TAB', cWhere)
Generics, z.B. oReader.Str<T>(…) Gibt es in der Skriptsprache nicht. Je Typ ein eigener Leser: Str, Int, Num, Bool.
Hilfsfunktion, die ein JSON-Fragment als Zeichenkette zurückgibt Den Writer als Parameter übergeben und an der richtigen Stelle hineinschreiben
oWriter.ArrEnd nach RootArr RootArr öffnet keine Ebene. Ein ArrEnd dazu ist ein Strukturfehler.
Zahlen selbst formatieren, z.B. mit NStr NStr liefert deutsche Schreibweise mit Tausenderpunkt. Für JSON oWriter.Num('preis', nWert, 2) verwenden.
fVal auf eine JSON-Zahl oReader.Num bzw. oReader.NumDef verwenden. Sie lesen den Dezimalpunkt richtig.
EMPTY_DATE für ein leeres Datum EMPTY_DATE ist im Skript eine Zeichenkette. Für Datumsvariablen und Vergleiche MINDATETIME verwenden.
TStringList für Zwischenlisten In Skripten unzuverlässig. Kleine Mengen als Zeichenkette mit Trennzeichen führen ('|' + wert + '|') und mit Pos prüfen.
Vorgabewerte für Parameter eigener Funktionen Werden nicht unterstützt. Alle Parameter ausschreiben.
qUpd.SaveData(…) als Anweisung ohne Auswertung Rückgabewert immer auswerten, siehe Schreibfehler erkennen
Je Feld ein eigener Aufruf zum Setzen Ein qSqlInit-Objekt, alle qSet, ein SaveData, siehe Mehrere Felder
Ein Wert je Zeile nachgeschlagen LEFT JOIN (1:1) oder Unterabfrage (1:n), siehe Keine Abfrage je Zeile
Ausgabeparameter vom Typ var … : TDateTime Bringt die Skriptausführung zum Absturz, und zwar erst beim Lesen des Werts. var string, var Integer und var Double laufen. Zeitpunkte als ISO-Zeichenkette zurückgeben und beim Aufrufer wandeln.

Skript-Cache

Der Server hält die Endpunkte samt Skript bis zu 60 Sekunden im Zwischenspeicher. Eine Änderung am Skript wirkt deshalb spätestens nach 60 Sekunden. Nach einem Neustart des Dienstes wirkt sie sofort.

Beispiel

Ein Endpunkt mit dem Pfad-Template /beispiel/tickets/{nr} liest ein Ticket und ändert seinen Status. Tabelle und Felder stehen für Ihre eigenen; Speichern ist die Prozedur aus Schreibfehler erkennen.

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql : string;
    qTick: TxFQuery;
    lGef : Boolean;
begin
    cSql := 'SELECT ti_nr, ti_betreff, ti_status FROM TICKETS' +
            ' WHERE ti_nr = ' + DB_SQLVal(oReader.Path('nr'));

    lGef := false;
    if (DB_SOpen(oDB, cSql, qTick)) then begin
        if (not qTick.EoF) then begin
            lGef := true;
            oWriter.Str('nr'     , AllTrim(qTick.A2C('ti_nr')));
            oWriter.Str('betreff', AllTrim(qTick.A2C('ti_betreff')));
            oWriter.Str('status' , AllTrim(qTick.A2C('ti_status')));
        end;
    end;
    DB_Close(qTick);

    if (not lGef) then begin
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
    end;
end;

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cNr    : string;
    cStatus: string;
    cUid   : string;
    cSql   : string;
    qTick  : TxFQuery;
    qUpd   : TqSQL;
begin
    cNr     := oReader.Path('nr');
    cStatus := '';
    if (not oReader.Str('status', cStatus)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
        exit;
    end;

    cUid := '';
    cSql := 'SELECT sys_uid FROM TICKETS WHERE ti_nr = ' + DB_SQLVal(cNr);
    if (DB_SOpen(oDB, cSql, qTick)) then begin
        if (not qTick.EoF) then begin
            cUid := qTick.A2UID();
        end;
    end;
    DB_Close(qTick);

    if (Empty(cUid)) then begin
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        exit;
    end;

    qUpd := qSqlInit(oDB, 'TICKETS');
    qUpd.qSet('sys_uid'  , cUid);
    qUpd.qSet('ti_status', cStatus);
    Speichern(qUpd, UPDATE_RECORD, 'Ticket');

    oWriter.Str('nr'    , cNr);
    oWriter.Str('status', cStatus);
end;

Aufruf des PUT mit curl:

curl -X PUT "https://obs.example.com:8443/beispiel/tickets/4711" \
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
  -H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"status": "9"}'

Weitere vollständige Beispiele:

Siehe auch