Zum Inhalt springen

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

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Scripting nach OBS/Kostenpflichtige Module/REST-Server/Scripting: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel)
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]
 
Zeile 5: Zeile 5:
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.
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 [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]].
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]].


== Aufruf ==
== Aufruf ==
Zeile 131: Zeile 131:
* Der Server liest den Körper als UTF-8.
* 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.
* 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/RESTServer/HTTP-Schnittstelle#Kompression|HTTP-Schnittstelle]].
* 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]].


=== Werte des Servers ===
=== Werte des Servers ===
Zeile 148: Zeile 148:
|}
|}


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/RESTServer/Anmeldung mit JWT#Claims im Endpunkt lesen|Anmeldung mit JWT]].
Bei Zugängen mit '''JWT-Authentifizierung''' stehen zusätzlich die Werte des Tokens bereit: <code>oReader.Subject()</code>, <code>oReader.Claim('&lt;name&gt;')</code>, <code>oReader.Param('_OBS_JWT_ID')</code>, <code>oReader.Param('_OBS_JWT_AUDIENCE')</code> sowie die Sitzungskennungen <code>sid</code> und <code>rid</code>. Die vollständige Liste steht unter [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT#Claims im Endpunkt lesen|Anmeldung mit JWT]].


=== Pfad-Parameter ===
=== Pfad-Parameter ===
Zeile 161: Zeile 161:
|}
|}


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/RESTServer/Beispiel4|Beispiel 4]].
Der '''Name''' ist geschützt: Ein Client kann einen Pfadwert nicht über Query oder Header unterschieben. Der '''Wert''' stammt aber aus der URL des Clients. Prüfen Sie ihn wie jede andere Eingabe, z.B. ob der Auftrag zum Mandanten im Token gehört. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4]].


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


Übertragung, Header und Statuscodes: [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]. Ein vollständiges Beispiel zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]].
Ü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]].


== Die Antwort schreiben: oWriter ==
== Die Antwort schreiben: oWriter ==
Zeile 278: Zeile 278:
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer?
| <code>oWriter.HasError()</code> || Steht schon eine Fehlerantwort im Writer?
|-
|-
| <code>oWriter.JwtRevoke('session')</code> || Sperrt die Sitzung des vorgelegten Tokens, mit <code>'all'</code> alle Sitzungen des Subjects. Siehe [[OBS/Kostenpflichtige Module/RESTServer/Anmeldung mit JWT#Abmelden aus einem Endpunkt|Anmeldung mit JWT]].
| <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.SendFile(cPfad, cName, cTyp)</code> || Eine Datei statt eines JSON-Körpers ausliefern. Die Datei bleibt liegen, der Download ist fortsetzbar.
Zeile 285: Zeile 285:
|}
|}


Dateiantworten beschreibt [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]].
Dateiantworten beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]].


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.
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.
Zeile 319: Zeile 319:


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


     // ... speichern, Version hochzaehlen ...
     // ... speichern, Version hochzählen ...
     oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
     oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
end;
end;
Zeile 362: Zeile 362:
* Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos.
* Nach Status 400 oder höher ist alles zurückgerollt und der Key wieder frei. Eine Wiederholung ist gefahrlos.


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


== Fehlerbehandlung im Skript ==
== Fehlerbehandlung im Skript ==
Zeile 382: Zeile 382:
{{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.}}
{{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.}}


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/RESTServer/HTTP-Schnittstelle#Fehlercodes|HTTP-Schnittstelle]].
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]].


=== Fehler im Protokoll ===
=== Fehler im Protokoll ===
Zeile 396: Zeile 396:
* Schreiben Sie für dieselbe Ablehnung keine eigene Protokollzeile. Der Server hat sie bereits.
* Schreiben Sie für dieselbe Ablehnung keine eigene Protokollzeile. Der Server hat sie bereits.


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


== Datenbankzugriff ==
== Datenbankzugriff ==
Zeile 445: Zeile 445:


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


== Anmeldeskript (JWT) ==
== 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/RESTServer/Anmeldung mit JWT#Das Anmeldeskript|Anmeldung mit 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 ==
== Gemeinsamen Code auslagern ==
Zeile 663: Zeile 663:


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


== Siehe auch ==
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]]
* [[OBS/Kostenpflichtige Module/REST-Server|REST-Server]]
* [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/RESTServer/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]
* [[OBS/Kostenpflichtige Module/RESTServer/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]]
* [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]
* [[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