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]
 
(12 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
|-
|-
| _OBS_JWT_SUBJECT    || Subject (''sub''-Claim) - typisch Benutzername
| <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_AUDIENCE    || Audience (''aud''-Claim) - typisch Mandant / Rolle
| <code>oReader.Offset()</code> || Nur der Offset daraus, z.B. ''+01:00''. Er geht in die [[#Zeitangaben|Zeitfunktionen]].
|-
|-
| _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.TraceId()</code> || Kennung der Anfrage
|-
|-
| _OBS_TRACE_ID        || Korrelations-ID des Requests (auch als Response-Header X-Trace-Id)
| <code>oReader.Param('_OBS_JWT_EXP_SEC')</code> || Laufzeit des Access-Tokens in Sekunden ('''Lebenszeit (Min)''' × 60)
|}
|}


Unabhängig von JWT stehen ausserdem immer zur Verfügung:
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 ===
Enthält das '''Pfad-Template''' Platzhalter, liefert <code>oReader.Path</code> deren Werte:


{| class="wikitable"
{| class="wikitable"
! Parameter            !! Inhalt
! Pfad-Template !! Zugriff im Skript
|-
|-
| _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
| <code>/beispiel/auftraege/{nr}</code> || <code>oReader.Path('nr')</code>
|-
|-
| _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
| <code>/beispiel/auftraege/{nr}/module/{code}</code> || <code>oReader.Path('nr')</code>, <code>oReader.Path('code')</code>
|}
|}


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


===Pfad-Parameter===
=== 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:
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
! Aufruf !! Inhalt
|-
|-
| <code>/orders/{uid}</code> || ''oParams.Values['_OBS_PATH_uid']''
| <code>oReader.UploadPath()</code> || Vollständiger Pfad der temporären Datei auf dem Server
|-
|-
| <code>/orders/{uid}/modules/{code}</code> || ''oParams.Values['_OBS_PATH_uid']'', ''oParams.Values['_OBS_PATH_code']''
| <code>oReader.UploadName()</code> || Originaler Dateiname
|-
| <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.
|}
|}


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]].
* 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.
* 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.
* Ein Upload-Körper wird nicht als JSON gelesen. <code>HasBody()</code> ist ''false''.
* 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'''.


===Datei-Uploads===
{{Hinweis|Der Server verschiebt die temporäre Datei nicht. Das Skript übernimmt sie an ihren Zielort.}}


Ist der Endpunkt für Uploads freigeschaltet (<code>re_upload = 1</code>, siehe
Ü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]].
[[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
== Die Antwort schreiben: oWriter ==
<code>Content-Range</code>-Upload - liefern dem Skript dieselben Parameter:
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>.
 
<syntaxhighlight lang="delphi">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
begin
    oWriter.Str('wert_string', '123');
    oWriter.Int('wert_int'  , 456);
end;
</syntaxhighlight>


{| class="wikitable"
{| class="wikitable"
! Parameter !! Inhalt
! Aufruf !! Ergebnis
|-
| <code>oWriter.Str('name', cWert)</code> || Zeichenkette, immer maskiert
|-
|-
| _OBS_UPLOAD_PATH || Vollständiger Pfad zur temporären Datei auf dem Server
| <code>oWriter.StrN('name', cWert)</code> || wie <code>Str</code>, aber <code>null</code> statt einer leeren Zeichenkette
|-
|-
| _OBS_UPLOAD_NAME || Originaldateiname
| <code>oWriter.Int('anz', nWert)</code> || Ganzzahl
|-
|-
| _OBS_UPLOAD_CONTENTTYPE || Content-Type der Datei (Default <code>application/octet-stream</code>, wenn der Client keinen angibt)
| <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
|}
|}


Der '''Dateiname ist Pflicht'''. Fehlt er, lehnt der Server den Upload mit
'''In einer Liste hat ein Eintrag keinen Namen.''' Der leere Feldname steht dafür:
'''400 Bad Request''' ab und das Skript wird nicht ausgeführt - das Skript kann
sich also darauf verlassen, dass ''_OBS_UPLOAD_PATH'' und ''_OBS_UPLOAD_NAME''
gesetzt sind, sobald es läuft.
 
{{Hinweis|Die temporäre Datei wird nicht automatisch verschoben. Das Skript muss sie an ihren Zielort (DMS, Verzeichnis, ...) übernehmen.}}


====Einfacher Upload (multipart/form-data)====
<syntaxhighlight lang="delphi">
 
oWriter.ArrBegin('dateien');
Eine Datei pro Request. Name und Content-Type stammen aus der
while (not qDat.EoF) do begin
<code>Content-Disposition</code> der Datei-Partie (<code>filename=</code>). Der
     oWriter.ObjBegin('');
Server speichert die erste Datei-Partie und ruft das Skript auf:
     oWriter.Str ('uid'     , qDat.A2C('f_uid'));
 
    oWriter.Int ('bytes'   , qDat.A2I('f_bytes'));
<syntaxhighlight lang="pascal" line>
    oWriter.StrN('kategorie', AllTrim(qDat.A2C('f_kat')));   // null, wenn leer
function Post(oParams: TStrings; oBody: TJSONObject): string;
    oWriter.ObjEnd;
var oRes : TJSONObject;
     qDat.Next();
    cPfad: string;
    cName: string;
    cTyp : string;
begin
     oRes := TJSONObject.Create();
     try
        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;
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
|-
| <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.
|-
|-
| Content-Range || Request || <code>bytes START-END/TOTAL</code>; <code>bytes */TOTAL</code> nur als Statusabfrage
| <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-Metadata || Request || tus-Metadaten im ersten Chunk: <code>filename</code> (Pflicht), <code>filetype</code> (optional), Base64-kodiert
| <code>oWriter.NoBody()</code> || Kein Körper, für '''204'''
|-
|-
| 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.Error(422, 'VALIDATION_FAILED', 'Feld "menge" fehlt')</code> || Fertige Fehlerantwort im Format des Servers, siehe [[#Fehlerbehandlung im Skript|Fehlerbehandlung]]
|-
|-
| Upload-Offset || Response || Anzahl der bereits gespeicherten Bytes (= Startoffset des nächsten Chunks)
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer?
|-
|-
| Range || Response || Bereits gespeicherter Bereich (<code>bytes=0-N</code>)
| <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]].


===Beispiel: Anlegen mit 201, Location und ETag===
<code>GET</code> läuft '''ohne''' Transaktion. Schreibt ein GET-Skript, wirkt jeder Schreibvorgang sofort und bleibt auch bei einer Fehlerantwort stehen.


<syntaxhighlight lang="pascal" line>
== Idempotenz ==
function Post(oParams: TStrings; oBody: TJSONObject): string;
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.
var oRes, oHdr: TJSONObject;
 
begin
Für das Skript gilt:
    oRes := TJSONObject.Create();
* Eine Wiederholung mit gespeicherter Antwort beantwortet der Server selbst. Das Skript läuft dabei nicht.
    try
* Gespeichert wird nur eine Antwort mit Status 2xx ohne Datei. Was sie enthält, ist eingefroren. Schreiben Sie die Antwort deshalb vollständig.
        // ... Datensatz anlegen, neue UID + Version (ETag) ermitteln ...
* 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.
        oHdr := TJSONObject.Create();
* Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos.
        oHdr.AddPair('Location', '/v1/orders/' + cNeueUid);
 
        oHdr.AddPair('ETag', '1');
Den Ablauf aus Sicht des Clients beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]].


        oRes.AddPair('_OBS_HTTP_STATUS', 201);
== Fehlerbehandlung im Skript ==
        oRes.AddPair('_OBS_HEADERS', oHdr);
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.
        oRes.AddPair('uid', cNeueUid);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
end;
</syntaxhighlight>


===Beispiel: Strukturierter Fehler mit Statuscode und traceId===
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, oErr: TJSONObject;
begin
begin
     oRes := TJSONObject.Create();
     if (Empty(oReader.Param('kundennr'))) then begin
    try
         oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "kundennr" fehlt');
        oErr := TJSONObject.Create();
         exit;
        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);
        oRes.AddPair('error', oErr);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
     end;
     end;
    // ...
end;
end;
</syntaxhighlight>
</syntaxhighlight>


===Beispiel: Optimistic Concurrency (ETag / If-Match)===
{{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.}}
 
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>
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 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
=== Fehler im Protokoll ===
            oHdr := TJSONObject.Create();
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:
            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="text">
        oHdr := TJSONObject.Create();
Fehler VALIDATION_FAILED [422 POST /beispiel/tickets] [trace=<traceId>]: Parameter "kundennr" fehlt
        oHdr.AddPair('ETag', xStr(nAktuell + 1));
        oRes.AddPair('_OBS_HEADERS', oHdr);
        result := oRes.ToJSON();
    finally
        MyFreeAndNil(oRes);
    end;
end;
</syntaxhighlight>
</syntaxhighlight>


==Idempotenz - was das Skript beachten muss==
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.


Sendet ein Konsument bei ''POST''/''PUT''/''PATCH''/''DELETE'' den Header
Protokoll und Suche über die <code>traceId</code>: [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]].
<code>Idempotency-Key</code>, fängt der '''Server''' doppelte Sendungen ab. Das
Skript braucht dafür '''keine eigene Logik''' - keine Schlüssel-Tabelle, keine
Prüfung am Anfang der Methode.


Was das Skript wissen muss:
== 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"
{| class="wikitable"
! Antwort des Skripts !! Wirkung auf den Idempotenz-Speicher
! Zweck !! Aufruf
|-
|-
| '''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
| 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>
|-
|-
| '''4xx''' || Der Schlüssel wird '''freigegeben'''. Der Konsument darf denselben Schlüssel nach Korrektur des Inhalts erneut verwenden
| 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>
|-
|-
| '''5xx''' oder Exception || Der Schlüssel bleibt belegt, der Fall wird protokolliert. Eine Wiederholung wird abgelehnt, bis der Fall geklärt ist
| Ä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>
|}
|}


Daraus folgen zwei Regeln für Endpunkt-Skripte:
=== Ändern: qSqlInit statt qSqlRead ===
Zum '''Ändern''' eines Satzes nehmen Sie ebenfalls <code>qSqlInit</code>. Die <code>sys_uid</code> adressiert den Satz:


* '''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.
<syntaxhighlight lang="delphi">
* '''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.
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>


{{Hinweis|Vor dieser Server-Funktion mussten Skripte die Idempotenz selbst
<code>qSqlRead</code> ist dafür die falsche Wahl:
abbilden. Solche Skripte laufen unverändert weiter - die Doppelprüfung schadet
* Es liest zuerst den kompletten Satz. Das kostet einen zusätzlichen Zugriff.
nicht, ist aber überflüssig und kann beim nächsten Überarbeiten entfallen.}}
* Es schreibt nur Änderungen. Ist der neue Wert gleich dem alten, liefert <code>SaveData</code> ''False'', genau wie bei einem echten Fehler.


Der vollständige Ablauf und die Statuscodes stehen unter
{{Hinweis|Ohne <code>sys_uid</code> legt <code>qSqlInit</code> einen '''neuen''' Satz an. Setzen Sie die <code>sys_uid</code> bei jeder Änderung.}}
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].


==JWT-Authentifizierungs-Skript==
Eine einzige Abfrage auf die <code>sys_uid</code> liefert Existenzprüfung und Schreibziel zugleich:


Bei Zugängen mit aktiver JWT-Pflicht wird über den JWT-Endpunkt das im Zugang hinterlegte Authentifizierungs-Skript aufgerufen (F7 in der Zugänge-Liste). Das Skript muss eine Methode ''Authenticate'' bereitstellen:
<syntaxhighlight lang="delphi">
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);


<syntaxhighlight lang="pascal" line>
if (not Empty(cUid)) then begin
function Authenticate(oParams: TStrings; oBody: TJSONObject): string;
    // ändern: qSqlInit mit sys_uid
var oRes  : TJSONObject;
end else begin
    cUser : string;
    // anlegen: qSqlInit ohne sys_uid
    cPass : string;
end;
begin
</syntaxhighlight>
    oRes := TJSONObject.Create();
 
    try
=== Mehrere Felder sind ein Schreibvorgang ===
        // Eingangsdaten lesen (Body oder Query-Param)
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:
        cUser := '';
 
        cPass := '';
<syntaxhighlight lang="delphi">
        if (Assigned(oBody)) then begin
// FALSCH: je Feld ein Aufruf mit eigener Abfrage und eigenem Schreibvorgang
            oVal := oBody.GetValue('username');
FeldSetzen(cUid, 'ti_status', '9');
            if (Assigned(oVal)) then begin
FeldSetzen(cUid, 'ti_grund' , cGrund);
                cUser := oVal.Value;
FeldSetzen(cUid, 'ti_von'  , cBenutzer);
            end;
 
            oVal := oBody.GetValue('password');
// RICHTIG: ein Schreibobjekt, ein SaveData
            if (Assigned(oVal)) then begin
qUpd := qSqlInit(oDB, 'TICKETS');
                cPass := oVal.Value;
qUpd.qSet('sys_uid'  , cUid);
            end;
qUpd.qSet('ti_status', '9');
        end;
qUpd.qSet('ti_grund' , cGrund);
qUpd.qSet('ti_von'   , cBenutzer);
Speichern(qUpd, UPDATE_RECORD, 'Ticket');
</syntaxhighlight>
 
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.
 
=== 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.
 
{{Hinweis|Ein GET soll lesen. Schreibvorgänge im Lesepfad vervielfachen sich mit der Zeilenzahl und laufen ohne Transaktion.}}
 
=== Schreibfehler erkennen ===
<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ö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.


        // 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 '''401''' und reicht den Wert von ''error'' als ''error.message'' an den Client durch (zusätzlich protokolliert)
| <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
|}
|}


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


Liefert das Skript einen anderen Status als 1 oder 9, ist gar nicht lauffähig oder
=== Bibliothek als eigener Endpunkt ===
gibt kein auswertbares JSON zurück, antwortet der Server mit '''403''' und einer
Am wenigsten Verwaltung macht eine Bibliothek als eigener Endpunkt:
generischen Meldung - ein defektes Anmeldeskript soll dem Anwender nicht als
# Legen Sie einen Endpunkt mit eigenem '''Pfad-Template''' an, z.B. <code>/meinapp/lib</code>.
„Passwort falsch" erscheinen.
# 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.


===Aufbau der Token-Antwort===
Eine Änderung an der Bibliothek gilt für alle Skripte, die sie einbinden.


Bei Erfolg baut der Server die Antwort aus den Token-Feldern '''und allen weiteren
{{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.}}
Feldern, die das Skript zurückgibt''':


{"benutzerId": "4711", "tenant": "nord", "roles": ["TECHNIKER"],
== Verfügbare Bibliotheken ==
  "token":       "eyJ...",
Im Skript stehen die OBS-Funktionen bereit, die Sie aus Makros kennen:
  "accessToken": "eyJ...",
* Zeichenketten, Datum, Zahlen und Konstanten wie <code>CRLF</code>, <code>SINGELQUOTE</code> und <code>MINDATETIME</code>
  "refreshToken":"eyJ...",
* Datenbank: lesen, schreiben, direkt ausführen
  "expiresIn":  28800,
* Dateifunktionen
  "serverTime":  "2026-08-17T09:12:33+02:00"}
* 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"
! Feld !! Herkunft
! Stolperstein !! Richtig
|-
|-
| token / accessToken || Derselbe Access-Token unter zwei Namen. ''accessToken'' erwarten die meisten Client-Bibliotheken, ''token'' bleibt für bestehende Konsumenten erhalten
| 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>
|-
|-
| refreshToken || Nur wenn das Skript ''_OBS_JWT_REFRESH_ID'' geliefert hat
| 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>.
|-
|-
| expiresIn || Laufzeit des Access-Tokens in '''Sekunden''' (''JWT-Exp'' × 60)
| Hilfsfunktion, die ein JSON-Fragment als Zeichenkette zurückgibt || Den Writer als Parameter übergeben und an der richtigen Stelle hineinschreiben
|-
|-
| serverTime || Serverzeit ISO-8601 mit Offset
| <code>oWriter.ArrEnd</code> nach <code>RootArr</code> || <code>RootArr</code> öffnet keine Ebene. Ein <code>ArrEnd</code> dazu ist ein Strukturfehler.
|-
|-
| alle übrigen Felder || '''Frei vom Skript bestimmt.''' Übernommen wird alles ausser ''status'' und den ''_OBS_''-Steuerfeldern
| 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.
Damit kann das Anmeldeskript alles mitliefern, was der Client direkt nach dem Login
|-
braucht (Benutzer-Id, Mandant, Rollen, Berechtigungen) - ohne dass dieser dafür
| <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.
einen zweiten Aufruf absetzen muss. Ein Feld, das genauso heisst wie eines der
|-
Token-Felder oben, wird verworfen; die Engine setzt diese selbst.
| <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.
 
|-
===Custom-Claims, serverTime und Refresh===
| Vorgabewerte für Parameter eigener Funktionen || Werden nicht unterstützt. Alle Parameter ausschreiben.
 
|-
Das Authenticate-Skript kann dem Token zusätzlich '''beliebige Custom-Claims''' mitgeben - z.B. Mandant und Rollen - und optional ein '''Refresh-Token''' anstoßen:
| <code>qUpd.SaveData(…)</code> als Anweisung ohne Auswertung || Rückgabewert immer auswerten, siehe [[#Schreibfehler erkennen|Schreibfehler erkennen]]
 
{| 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;'].
| 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]]
|-
|-
| _OBS_JWT_REFRESH_ID || (optional) jti des Refresh-Tokens. Nur wenn gesetzt, stellt der Server ein Refresh-Token aus.
| Ein Wert je Zeile nachgeschlagen || <code>LEFT JOIN</code> (1:1) oder Unterabfrage (1:n), siehe [[#Keine Abfrage je Zeile|Keine Abfrage je Zeile]]
|-
|-
| _OBS_JWT_REFRESH_EXP || (optional) Lebensdauer des Refresh-Tokens in Minuten (Default 90 Tage = 129600).
| 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"}
 
{{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>'' 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.
== 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]].


<syntaxhighlight lang="pascal" line>
<syntaxhighlight lang="delphi">
function Refresh(oParams: TStrings; oBody: TJSONObject): string;
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var oRes: TJSONObject;
var cSql : string;
     cAltesJti, cNeuesJti: string;
    qTick: TxFQuery;
     lGef : Boolean;
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;
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.
    cStatus: string;
 
    cUid  : string;
Server-eigene Fehler (Routing, Rate-Limit, Token, Auffangnetz) haben ein
    cSql  : string;
einheitliches Format mit einem ''error''-Objekt - Aufbau siehe
    qTick  : TxFQuery;
[[OBS/Kostenpflichtige Module/RESTServer|Übersicht]].
    qUpd  : TqSQL;
 
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
begin
     oRes := TJSONObject.Create();
     cNr    := oReader.Path('nr');
     try
     cStatus := '';
        if (Empty(oParams.Values['kundennr'])) then begin
    if (not oReader.Str('status', cStatus)) then begin
            oErr := TJSONObject.Create();
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
            oErr.AddPair('code'  , 'VALIDATION_FAILED');
        exit;
            oErr.AddPair('message', 'Parameter ''kundennr'' fehlt');
    end;
            oErr.AddPair('traceId', oParams.Values['_OBS_TRACE_ID']);


            oRes.AddPair('_OBS_HTTP_STATUS', 422);
    cUid := '';
            oRes.AddPair('error', oErr);
    cSql := 'SELECT sys_uid FROM TICKETS WHERE ti_nr = ' + DB_SQLVal(cNr);
             result := oRes.ToJSON();
    if (DB_SOpen(oDB, cSql, qTick)) then begin
            exit;
        if (not qTick.EoF) then begin
             cUid := qTick.A2UID();
         end;
         end;
        // ...
    finally
        MyFreeAndNil(oRes);
     end;
     end;
end;
    DB_Close(qTick);
</syntaxhighlight>


{{Hinweis|Ein fachlicher Fehler gehört auf einen '''4xx'''-Statuscode, nicht auf
    if (Empty(cUid)) then begin
200 mit Fehlertext im Body. Nur so erkennt der Konsument den Fehlschlag ohne den
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
Body auszuwerten - und nur so gibt der Server einen belegten
        exit;
''Idempotency-Key'' wieder frei (siehe Abschnitt Idempotenz).}}
    end;


Gängige Codes, die auch der Server selbst verwendet: ''VALIDATION_FAILED'' (422),
    qUpd := qSqlInit(oDB, 'TICKETS');
''NOT_FOUND'' (404), ''FORBIDDEN_ROLE'' (403), ''VERSION_CONFLICT'' (409).
    qUpd.qSet('sys_uid' , cUid);
Eigene, fachlich sprechende Codes sind erlaubt - wichtig ist, dass sie stabil
    qUpd.qSet('ti_status', cStatus);
bleiben, weil Konsumenten darauf ihre Reaktion aufbauen.
    Speichern(qUpd, UPDATE_RECORD, 'Ticket');


==Skript-Cache==
    oWriter.Str('nr'    , cNr);
    oWriter.Str('status', cStatus);
end;
</syntaxhighlight>


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.
Aufruf des PUT mit curl:


==Verfügbare Bibliotheken==
<syntaxhighlight lang="bash">
 
curl -X PUT "https://obs.example.com:8443/beispiel/tickets/4711" \
Im Skript können alle OBS-Standard-Bibliotheken verwendet werden. Typische Einstiegspunkte:
  -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
 
  -H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
* ''Base.Tools'' - String-, Datum-, IIF-, Empty-Helper
  -H "Content-Type: application/json; charset=utf-8" \
* ''Base.DB'' / ''Base.xQuery'' - Datenbank-Operationen, ''DB_SQLVal'', ''DB_SOpen'', ''DB_LSeek''
  -d '{"status": "9"}'
* ''Base.qSqlReg'' - ''qSqlInit'', ''qSet'', ''SaveData''
</syntaxhighlight>
* ''System.JSON'' - JSON-Objekte und -Arrays
* ''Base.ToolsConst'' - Konstanten wie ''CRLF'', ''SINGELQUOTE'', ''EMPTY_DATE''


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