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]
 
(13 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]].
|}


Nicht implementierte Methoden liefern automatisch ''405''-ähnliche Fehler über die generische Skript-Antwort.
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.


==Parameter==
== 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 <code>DB_SQLVal</code> ein und prüfen Sie Eingaben gegen erlaubte Werte.}}


===oParams (TStrings)===
* 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 <code>message</code> geht an den Client.


Enthält alle Query-Parameter, POST-Parameter (form-urlencoded) sowie die durchgereichten HTTP-Header. Werte sind immer Strings.
== Die Anfrage lesen: oReader ==
<code>oReader</code> ist der einzige Zugang zur Anfrage. Alle Werte sind Zeichenketten oder werden über einen typisierten Leser geholt.


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


* Geblockte Header werden nicht durchgereicht: ''authorization'', ''cookie'', ''proxy-authorization'', ''x-forwarded-for'', ''x-real-ip'', ''apikey'', ''api_key''.
Was der Server vorher filtert:
* Parameter mit Präfix '''_OBS_''' können von aussen nicht gesetzt werden; sie sind für interne Werte reserviert.
* 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.
* Werte werden auf max. 1024 Zeichen begrenzt.
* Namen, die mit <code>_OBS_</code> beginnen, sind dem Server vorbehalten. Header und Query-Parameter mit solchen Namen verwirft er.
* Null-Bytes und Steuerzeichen (ausser Tab, CR, LF) werden entfernt.
* Werte aus Header, Query, Pfad und Formular kürzt er nach 1024 Zeichen.
* Null-Bytes und Steuerzeichen entfernt er. Tabulator, CR und LF bleiben.


Zugriff im Skript:
<syntaxhighlight lang="delphi">
cKundenNr := oReader.Param('kundennr');
if (not Empty(cKundenNr)) then begin
    // ...
end;
</syntaxhighlight>


if (not Empty(oParams.Values['kundennr'])) then begin
=== Der Körper ===
    cKundenNr := oParams.Values['kundennr'];
Den JSON-Körper liest <code>oReader</code> über '''Pfade'''. Es gibt keine Unterobjekte, keine Typumwandlung und nichts freizugeben.
end;


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


Enthält den Request-Body, sofern dieser ein gültiges JSON-Objekt ist. Bei leerem oder nicht-JSON-Body wird ''nil'' übergeben.
Verschachtelung steht im Pfad: Punkt für Felder, eckige Klammern für Listen.


cUser := '';
<syntaxhighlight lang="delphi">
  cPass := '';
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
if (Assigned(oBody)) then begin
var cVon: string;
    oVal := oBody.GetValue('username');
    nAnz: Integer;
    if (Assigned(oVal)) then begin
    nI : Integer;
        cUser := oVal.Value;
begin
    end;
    nAnz := oReader.Count('zeiten');
    oVal := oBody.GetValue('password');
    for nI := 0 to nAnz - 1 do begin
    if (Assigned(oVal)) then begin
        if (oReader.Str('zeiten[' + IntToStr(nI) + '].von', cVon)) then begin
        cPass := oVal.Value;
            // ... cVon verarbeiten ...
    end;
        end;
end;
    end;
end;
</syntaxhighlight>


Maximale Body-Grösse: 10 MB.
{{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“.}}


===Reservierte _OBS_-Parameter===
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]].


Bei aktiver JWT-Authentifizierung stehen die Token-Claims als Parameter zur Verfügung:
=== Werte des Servers ===
Diese Werte setzt der Server. Ein Client kann sie nicht überschreiben.


{| class="wikitable"
{| class="wikitable"
! Parameter            !! Inhalt
! Aufruf !! Inhalt
|-
|-
| _OBS_JWT_ID          || JWT-Id (''jti''-Claim) - typisch die User-Id
| <code>oReader.Param('_OBS_SERVER_TIME')</code> || Serverzeit nach ISO 8601 mit UTC-Offset, z.B. ''2026-11-17T09:12:33+01:00''
|-
|-
| _OBS_JWT_SUBJECT    || Subject (''sub''-Claim) - typisch Benutzername
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+01:00''. Er geht in die [[#Zeitangaben|Zeitfunktionen]].
|-
|-
| _OBS_JWT_AUDIENCE    || Audience (''aud''-Claim) - typisch Mandant / Rolle
| <code>oReader.TraceId()</code> || Kennung der Anfrage
|-
|-
| _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.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden ('''Lebenszeit (Min)''' × 60)
|-
| _OBS_TRACE_ID        || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
|}
|}


Diese Werte werden vom Server gesetzt und können vom Skript für Berechtigungs- und Mandantenprüfungen verwendet werden.
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]].


===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===
=== 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:
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
<code>Content-Range</code>-Upload - liefern dem Skript dieselben Parameter:


{| 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>.
|-
| <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.
* 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|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}
{{Hinweis|Der Server verschiebt die temporäre Datei nicht. Das Skript übernimmt sie an ihren Zielort.}}


====Einfacher Upload (multipart/form-data)====
Ü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]].


Eine Datei pro Request. Name und Content-Type stammen aus der
== Die Antwort schreiben: oWriter ==
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
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>.
Server speichert die erste Datei-Partie und ruft das Skript auf:


<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'];
end;
        cName := oParams.Values['_OBS_UPLOAD_NAME'];
</syntaxhighlight>
        cTyp  := oParams.Values['_OBS_UPLOAD_CONTENTTYPE'];


        // ... Datei aus cPfad ins DMS / Zielverzeichnis uebernehmen ...
{| class="wikitable"
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
| <code>oWriter.StrN('name', cWert)</code> || wie <code>Str</code>, aber <code>null</code> statt einer leeren Zeichenkette
|-
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
| <code>oWriter.Num('preis', nWert, 2)</code> || Kommazahl mit fester Stellenzahl. Immer mit Dezimalpunkt, unabhängig von den Ländereinstellungen des Servers.
|-
| <code>oWriter.Bool('aktiv', lWert)</code> || <code>true</code> oder <code>false</code>
|-
| <code>oWriter.Null('lat')</code> || ausdrücklich <code>null</code>
|-
| <code>oWriter.ObjBegin('kunde')</code> … <code>oWriter.ObjEnd</code> || Unterobjekt
|-
| <code>oWriter.ArrBegin('dateien')</code> … <code>oWriter.ArrEnd</code> || Liste
|-
| <code>oWriter.RootArr()</code> || Die Wurzel ist eine Liste statt eines Objekts. Steht vor dem ersten Feld. Ein <code>ArrEnd</code> gehört nicht dazu.
|-
| <code>oWriter.Raw('meta', cJson)</code> || Fertiges JSON-Fragment einbetten, siehe unten
|}


        oRes.AddPair('status'   , 'ok');
'''In einer Liste hat ein Eintrag keinen Namen.''' Der leere Feldname steht dafür:
        oRes.AddPair('dateiname', cName);
 
        result := oRes.ToJSON();
<syntaxhighlight lang="delphi">
     finally
oWriter.ArrBegin('dateien');
        MyFreeAndNil(oRes);
while (not qDat.EoF) do begin
     end;
    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;
end;
oWriter.ArrEnd;
</syntaxhighlight>
</syntaxhighlight>


====Resumable/Chunked Upload (Content-Range)====
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.


Für grosse Dateien überträgt der Client die Datei in Teilstücken (Chunks) mit dem
{{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:
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;
<code>procedure DateienSchreiben(oWriter: TxRestWriter; const cNr: string);</code>}}
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>
<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.
Upload-Metadata: filename ZmlsZS5wZGY=,filetype YXBwbGljYXRpb24vcGRm
</pre>


Erkannt werden die Schlüssel <code>filename</code> (Pflicht) und
=== Zeitangaben ===
<code>filetype</code> (optional). Fehlt <code>filename</code> im ersten Chunk,
Zeitpunkte gehen als ISO 8601 mit Offset über die Leitung. Für die Umwandlung gibt es eigene Funktionen:
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 !! Zweck
|-
|-
| 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>RestIsoFromDate(dWert, cOffset)</code> || OBS-Zeitpunkt in ''2026-09-09T14:12:00+02:00''. Leere Zeichenkette bei leerem Datum.
|-
|-
| weitere Chunks (jeweils <code>Upload-Id</code> mitsenden) || '''308''' mit aktualisiertem <code>Upload-Offset</code>
| <code>RestDateFromIso(cWert, cOffset)</code> || ISO-Zeichenkette in einen OBS-Zeitpunkt in Ortszeit des Servers
|-
|-
| letzter Chunk (Bereich erreicht TOTAL) || normale Skript-Antwort (z.B. '''200'''/'''201''')
| <code>oReader.Offset()</code> || Der Offset für beide Funktionen
|-
|-
| Statusabfrage <code>Content-Range: bytes */5000000</code> || aktueller <code>Upload-Offset</code>, ohne anzuhängen (Resume)
| <code>RestOffsetToMinutes(cOffset)</code> || 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.


{| class="wikitable"
{| class="wikitable"
! Header !! Richtung !! Bedeutung
! Aufruf !! Wirkung
|-
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
| <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.
|-
|-
| Upload-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
| <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.
|-
|-
| 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.NoBody()</code> || Kein Körper, für '''204'''
|-
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
| <code>oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt')</code> || Fertige Fehlerantwort im Format des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
| <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.
|}
|}


Der Server hängt einen Chunk '''nur an, wenn START dem bereits gespeicherten Stand
Dateiantworten beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]].
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''),
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.
antwortet der Server mit '''413 Payload Too Large'''.


{{Hinweis|Der Upload-Status liegt prozesslokal im Speicher. Nach einem Neustart des Servers muss ein unvollständiger Upload neu begonnen werden.}}
Setzt das Skript den Header <code>Content-Encoding</code> selbst, packt der Server die Antwort nicht noch einmal.


==Rückgabe==
=== Beispiel: Anlegen mit 201, Location und ETag ===
<syntaxhighlight lang="delphi">
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cNeueNr: string;
begin
    // ... Datensatz anlegen, neue Nummer ermitteln ...


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.
    oWriter.Str('nr', cNeueNr);
    oWriter.Status(201);
    oWriter.Header('Location', '/beispiel/tickets/' + cNeueNr);
    oWriter.Header('ETag'   , '"1"');
end;
</syntaxhighlight>


Einfaches Beispiel:
=== 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 Get(oParams: TStrings; oBody: TJSONObject): string;
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var oRes: TJSONObject;
var nAktuell: Integer;
    cETag  : string;
    cIfMatch: string;
begin
begin
     oRes := TJSONObject.Create();
     nAktuell := TicketVersion(oReader.Path('nr'));   // eigene Funktion
     try
     cETag    := '"' + IntToStr(nAktuell) + '"';
        oRes.AddPair('wert_string', '123');
    cIfMatch := AllTrim(oReader.Param('if-match'));
         oRes.AddPair('wert_int'   , 456);
 
         result := oRes.ToJSON();
    if (cIfMatch <> cETag) and (cIfMatch <> IntToStr(nAktuell)) then begin
    finally
         // Der gültige ETag gehört auch an die Ablehnung,
         MyFreeAndNil(oRes);
        // 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;
     end;
    // ... speichern, Version hochzählen ...
    oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
end;
end;
</syntaxhighlight>
</syntaxhighlight>


==Antwort steuern: Statuscode, Header, traceId==
<code>VERSION_CONFLICT</code> ist hier ein eigener Code des Skripts. Der Server selbst verwendet für '''409''' den Code <code>CONFLICT</code>.


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.
== Transaktion ==
<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.


{| class="wikitable"
{| class="wikitable"
! Antwort-Feld !! Wirkung
! Ende des Skripts !! Wirkung
|-
| Status unter 400 || Alle Änderungen werden festgeschrieben.
|-
|-
| _OBS_HTTP_STATUS (Zahl) || HTTP-Statuscode (z.B. 201, 204, 400, 409, 422). Ohne Angabe: 200. Bei 204 wird kein Body gesendet.
| Status 400 oder höher || Alle Änderungen werden zurückgerollt.
|-
|-
| _OBS_HEADERS (Objekt) || Beliebige Response-Header, z.B. ETag, Location, Retry-After. CR/LF in Namen/Werten werden entfernt (Schutz vor Header-Injection).
| Exception oder Skriptfehler || Alle Änderungen werden zurückgerollt, der Client erhält '''500'''.
|}
|}


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.
* '''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]].
 
<code>GET</code> läuft '''ohne''' Transaktion. Schreibt ein GET-Skript, wirkt jeder Schreibvorgang sofort und bleibt auch bei einer Fehlerantwort stehen.
 
== Idempotenz ==
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.
 
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 [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].
 
== 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.


===Beispiel: Anlegen mit 201, Location und ETag===
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>.


<syntaxhighlight lang="pascal" line>
<syntaxhighlight lang="delphi">
function Post(oParams: TStrings; oBody: TJSONObject): string;
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var oRes, oHdr: TJSONObject;
begin
begin
     oRes := TJSONObject.Create();
     if (Empty(oReader.Param('kundennr'))) then begin
    try
         oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
        // ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...
         exit;
        oHdr := TJSONObject.Create();
        oHdr.AddPair('Location', '/v1/orders/' + cNeueUid);
        oHdr.AddPair('ETag', '1');
 
         oRes.AddPair('_OBS_HTTP_STATUS', 201);
        oRes.AddPair('_OBS_HEADERS', oHdr);
        oRes.AddPair('uid', cNeueUid);
         result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
     end;
     end;
    // ...
end;
end;
</syntaxhighlight>
</syntaxhighlight>


===Beispiel: Strukturierter Fehler mit Statuscode und traceId===
{{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.}}


<syntaxhighlight lang="pascal" line>
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]].
function Post(oParams: TStrings; oBody: TJSONObject): string;
 
var oRes, oErr: TJSONObject;
=== Fehler im Protokoll ===
begin
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:
    oRes := TJSONObject.Create();
    try
        oErr := TJSONObject.Create();
        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);
<syntaxhighlight lang="text">
        oRes.AddPair('error', oErr);
Fehler VALIDATION_FAILED [422 POST /beispiel/tickets] [trace=<traceId>]: Parameter "kundennr" fehlt
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
end;
</syntaxhighlight>
</syntaxhighlight>


===Beispiel: Optimistic Concurrency (ETag / If-Match)===
Daraus folgt:
* Verwenden Sie <code>oWriter.Error</code>. 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 <code>message</code>. 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 <code>traceId</code>: [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]].
 
== Datenbankzugriff ==
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>.
 
{| class="wikitable"
! Zweck !! Aufruf
|-
| 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>
|-
| 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>
|-
| Ä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>
|-
| Direkt ausführen || <code>DB_SqlExec(oDB, cSql)</code>
|-
| Existenz prüfen || <code>DB_LSeek(oDB, 'TAB', cWhere)</code>
|-
| Werte einsetzen (Pflicht) || <code>DB_SQLVal(wert)</code>
|}
 
=== Ändern: qSqlInit statt qSqlRead ===
Zum '''Ändern''' eines Satzes nehmen Sie ebenfalls <code>qSqlInit</code>. Die <code>sys_uid</code> adressiert den Satz:
 
<syntaxhighlight lang="delphi">
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
</syntaxhighlight>


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:
<code>qSqlRead</code> 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 <code>SaveData</code> ''False'', genau wie bei einem echten Fehler.


<syntaxhighlight lang="pascal" line>
{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen''' Satz an. Setzen Sie die <code>sys_uid</code> bei jeder Änderung.}}
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
Eine einzige Abfrage auf die <code>sys_uid</code> liefert Existenzprüfung und Schreibziel zugleich:
            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 ...
<syntaxhighlight lang="delphi">
        oHdr := TJSONObject.Create();
cUid := '';
        oHdr.AddPair('ETag', xStr(nAktuell + 1));
if (DB_SOpen(oDB, 'SELECT sys_uid FROM TICKETS WHERE ' + cWhere + ' LIMIT 1', qDat)) then begin
        oRes.AddPair('_OBS_HEADERS', oHdr);
    if (not qDat.EoF) then begin
         result := oRes.ToJSON();
         cUid := qDat.A2UID();
    finally
        MyFreeAndNil(oRes);
     end;
     end;
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;
</syntaxhighlight>
=== 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:
<syntaxhighlight lang="delphi">
// 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');
</syntaxhighlight>
</syntaxhighlight>


==JWT-Authentifizierungs-Skript==
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.


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:
=== 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.


<syntaxhighlight lang="pascal" line>
{{Hinweis|Ein GET soll lesen. Schreibvorgänge im Lesepfad vervielfachen sich mit der Zeilenzahl und laufen ohne Transaktion.}}
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
 
var oRes  : TJSONObject;
=== Schreibfehler erkennen ===
    cUser : string;
<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
    cPass : string;
* löst das '''keine''' Exception aus,
begin
* steht '''nichts''' in <code>RESTSRV_PROTO</code>,
    oRes := TJSONObject.Create();
* läuft das Skript weiter und meldet den Erfolg, den es selbst schreibt.
    try
        // Eingangsdaten lesen (Body oder Query-Param)
        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, ...
Prüfen Sie den Rückgabewert deshalb immer. Am einfachsten über eine kleine Prozedur in der gemeinsamen Bibliothek:
        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();
<syntaxhighlight lang="delphi">
     finally
procedure Speichern(qUpd: TqSQL; lNeu: Boolean; const cWas: string);
         MyFreeAndNil(oRes);
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;
end;
end;
// Aufruf statt SaveData und qSqlFree:
qUpd := qSqlInit(oDB, 'TICKETS');
qUpd.qSet('ti_betreff', cBetreff);
Speichern(qUpd, NEW_RECORD, 'Ticket');
</syntaxhighlight>
</syntaxhighlight>


Rückgabewerte:
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.
 
== 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]].
 
== 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:
 
<syntaxhighlight lang="delphi">
{$L T="restsrv_endpoints" I="re_pathtemplate" V="/meinapp/lib" F="re_script"}
</syntaxhighlight>


{| class="wikitable"
{| class="wikitable"
! status !! Bedeutung
! Attribut !! Bedeutung
|-
|-
| 1      || Erfolgreich, der Server erzeugt aus den ''_OBS_JWT_*''-Werten einen Token (HS256)
| <code>T</code> || Tabelle, aus der geladen wird
|-
|-
| 9      || Misserfolg, der Server antwortet mit 403 und protokolliert den Wert von ''error''
| <code>I</code> || Spalte, über die gesucht wird
|-
| <code>V</code> || Wert, der in dieser Spalte stehen muss
|-
| <code>F</code> || Spalte, deren Inhalt an dieser Stelle eingesetzt wird
|}
|}


===Custom-Claims, serverTime und Refresh===
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.


Das Authenticate-Skript kann dem Token zusÄtzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:
=== 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.


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 <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
Eine JSON-Bibliothek braucht ein Endpunkt-Skript nicht. Der Reader liest den Körper, der Writer erzeugt die Antwort.
== Fallstricke im Skript ==
{| class="wikitable"
{| class="wikitable"
! RÜckgabefeld !! Bedeutung
! Stolperstein !! Richtig
|-
| 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>
|-
| 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>.
|-
|-
| _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;'].
| Hilfsfunktion, die ein JSON-Fragment als Zeichenkette zurückgibt || Den Writer als Parameter übergeben und an der richtigen Stelle hineinschreiben
|-
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
| <code>oWriter.ArrEnd</code> nach <code>RootArr</code> || <code>RootArr</code> öffnet keine Ebene. Ein <code>ArrEnd</code> dazu ist ein Strukturfehler.
|-
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
| 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.
|-
| <code>fVal</code> auf eine JSON-Zahl || <code>oReader.Num</code> bzw. <code>oReader.NumDef</code> verwenden. Sie lesen den Dezimalpunkt richtig.
|-
| <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.
|-
| <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.
|-
| Vorgabewerte für Parameter eigener Funktionen || Werden nicht unterstützt. Alle Parameter ausschreiben.
|-
| <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.
|}
|}


Jedes Token trÄgt automatisch den Claim ''token_use'' (''access'' bzw. ''refresh''). Die Antwort enthÄlt bei Erfolg ''serverTime'' (ISO-8601 mit Offset), bei ausgestelltem Refresh zusÄtzlich ''refreshToken'':
== 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.


{"token":"...", "refreshToken":"...", "serverTime":"2026-06-29T15:30:12+02:00"}
== 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]].


{{Hinweis|Mandant und Rollen immer aus dem Token lesen (''_OBS_JWT_CLAIM_*''), nie aus Body oder Query.}}
<syntaxhighlight lang="delphi">
 
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
====Refresh-Methode====
var cSql : string;
 
    qTick: TxFQuery;
Der Refresh lÄuft Über '''denselben JWT-Endpunkt''' und '''dasselbe Skript'''. Liegt am JWT-Endpunkt ein ''Authorization: Bearer <token>'' vor, ruft der Server statt ''Authenticate'' die Methode '''Refresh''' auf (sonst Login). Der Server verifiziert den Refresh-Token zuvor (Signatur, Ablauf, ''token_use=refresh''); das alte Refresh-jti steht als ''oParams.Values['_OBS_JWT_ID']'' bereit. Das Skript prÜft/rotiert seine Sperrtabelle und liefert wie ''Authenticate'' neue Claims zurÜck. Der Server stellt daraufhin ein rotiertes Token-Paar aus; ein bereits benutztes Refresh-Token wird mit 401 abgelehnt.
     lGef : Boolean;
 
<syntaxhighlight lang="pascal" line>
function Refresh(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
     cAltesJti, cNeuesJti: string;
begin
begin
     oRes := TJSONObject.Create();
     cSql := 'SELECT ti_nr, ti_betreff, ti_status FROM TICKETS' +
    try
            ' WHERE ti_nr = ' + DB_SQLVal(oReader.Path('nr'));
        cAltesJti := oParams.Values['_OBS_JWT_ID'];


        // altes Refresh-jti gegen eigene Sperrtabelle prÜfen
    lGef := false;
         if (not RefreshJtiGueltig(cAltesJti)) then begin
    if (DB_SOpen(oDB, cSql, qTick)) then begin
             oRes.AddPair('status', 9);
         if (not qTick.EoF) then begin
             oRes.AddPair('error' , 'AUTH_EXPIRED');
             lGef := true;
             result := oRes.ToJSON();
            oWriter.Str('nr'     , AllTrim(qTick.A2C('ti_nr')));
            exit;
             oWriter.Str('betreff', AllTrim(qTick.A2C('ti_betreff')));
             oWriter.Str('status' , AllTrim(qTick.A2C('ti_status')));
         end;
         end;
    end;
    DB_Close(qTick);


        cNeuesJti := GlobalUID();
    if (not lGef) then begin
        RefreshJtiRotieren(cAltesJti, cNeuesJti);  // altes sperren, neues ablegen
         oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
 
         oRes.AddPair('status'              , 1);
        oRes.AddPair('_OBS_JWT_ID'         , GlobalUID());
        oRes.AddPair('_OBS_JWT_SUBJECT'     , oParams.Values['_OBS_JWT_SUBJECT']);
        oRes.AddPair('_OBS_JWT_CLAIM_tenant', oParams.Values['_OBS_JWT_CLAIM_tenant']);
        oRes.AddPair('_OBS_JWT_CLAIM_roles' , oParams.Values['_OBS_JWT_CLAIM_roles']);
        oRes.AddPair('_OBS_JWT_REFRESH_ID'  , cNeuesJti);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
     end;
     end;
end;
end;
</syntaxhighlight>


==Fehlerbehandlung im Skript==
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;


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.
    cUid := '';
 
     cSql := 'SELECT sys_uid FROM TICKETS WHERE ti_nr = ' + DB_SQLVal(cNr);
Will das Skript einen spezifischen Fehler an den Konsumenten zurückgeben, ist eine eigene JSON-Struktur zu liefern:
     if (DB_SOpen(oDB, cSql, qTick)) then begin
 
        if (not qTick.EoF) then begin
<syntaxhighlight lang="pascal" line>
             cUid := qTick.A2UID();
function Post(oParams: TStrings; oBody: TJSONObject): string;
var oRes: TJSONObject;
begin
     oRes := TJSONObject.Create();
     try
        if (Empty(oParams.Values['kundennr'])) then begin
            oRes.AddPair('status', 'error');
            oRes.AddPair('msg'  , 'Parameter ''kundennr'' fehlt');
             result := oRes.ToJSON();
            exit;
         end;
         end;
        // ...
    finally
        MyFreeAndNil(oRes);
     end;
     end;
end;
    DB_Close(qTick);
</syntaxhighlight>


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


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.
    qUpd := qSqlInit(oDB, 'TICKETS');
    qUpd.qSet('sys_uid' , cUid);
    qUpd.qSet('ti_status', cStatus);
    Speichern(qUpd, UPDATE_RECORD, 'Ticket');


==Verfügbare Bibliotheken==
    oWriter.Str('nr'    , cNr);
    oWriter.Str('status', cStatus);
end;
</syntaxhighlight>


Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:
Aufruf des PUT mit curl:


* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
<syntaxhighlight lang="bash">
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen, ''DB_SQLVal'', ''DB_SOpen'', ''DB_LSeek''
curl -X PUT "https://obs.example.com:8443/beispiel/tickets/4711" \
* ''Base.qSqlReg'' - ''qSqlInit'', ''qSet'', ''SaveData''
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
* ''System.JSON'' - JSON-Objekte und -Arrays
  -H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''EMPTY_DATE''
  -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: Daten-Abruf mit JWT]]
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel2|Beispiel: Datensatz anlegen mit JSON-Body]]
* [[OBS/Kostenpflichtige Module/REST-Server|REST-Server]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel: Pfad-Parameter im Routing]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel5|Beispiel: Schreibzugriff mit Statuscodes, ETag und Idempotenz]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[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