Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter: Unterschied zwischen den Versionen

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(3 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
= Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) =
{{Seitentyp|Referenz}}
= Pfad-Parameter =


Dieses Beispiel zeigt das '''Pfad-Template-Routing''' mit Platzhaltern. Eine
Dieses Beispiel zeigt das Routing über '''Pfad-Templates''' mit Platzhaltern. So entstehen sprechende Adressen, wie sie Entwickler von modernen REST-Schnittstellen erwarten. Eine Auftrags-Ressource wird über drei Endpunkte abgebildet:
Auftrags-Ressource wird über drei Endpunkte abgebildet:


{| class="wikitable"
{| class="wikitable"
! Methode + Pfad !! Zweck
! Methode und Pfad !! Zweck
|-
|-
| <code>GET /orders</code> || Liste aller offenen Aufträge
| <code>GET /orders</code> || Liste aller offenen Aufträge
|-
|-
| <code>GET /orders/{uid}</code> || Einzelner Auftrag per UID
| <code>GET /orders/{uid}</code> || Einzelner Auftrag über seine UID
|-
|-
| <code>PUT /orders/{uid}/modules/{code}</code> || Status eines Auftrags-Moduls ändern
| <code>PUT /orders/{uid}/modules/{code}</code> || Status eines Auftrags-Moduls ändern
|}
|}


Die Platzhalter <code>{uid}</code> und <code>{code}</code> stehen im Skript als
Die Platzhalter <code>{uid}</code> und <code>{code}</code> stehen im Skript über <code>oReader.Path('uid')</code> bzw. <code>oReader.Path('code')</code> bereit.
<code>oReader.Path('uid')</code> bzw. <code>oReader.Path('code')</code> zur
Verfügung.


== Einrichtung in OBS ==
== Einrichtung in OBS ==
 
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443
* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'' auf <code>0.0.0.0:443</code>.
* '''Zugang:''' ''Orders-Client'' mit '''API-Key''', berechtigt für die drei Endpunkte
* '''Zugang:''' ''Orders-Client'' mit API-Key, Zugriff auf die drei Endpunkte.
* '''Endpunkte''', alle mit '''Server''' ''Public-API'':
* '''Endpunkte''' (je ein Eintrag in <code>RESTSRV_ENDPOINTS</code>, alle Profil ''Public-API''):


{| class="wikitable"
{| class="wikitable"
! Endpunkt !! Pfad-Template !! Skript-Methode
! Pfad-Template !! Skriptmethode
|-
|-
| <code>orders</code> || <code>/orders</code> || <code>Get</code> (Liste)
| <code>/orders</code> || <code>Get</code> (Liste)
|-
|-
| <code>orders</code> || <code>/orders/{uid}</code> || <code>Get</code> (Einzel)
| <code>/orders/{uid}</code> || <code>Get</code> (einzelner Auftrag)
|-
|-
| <code>orders</code> || <code>/orders/{uid}/modules/{code}</code> || <code>Put</code>
| <code>/orders/{uid}/modules/{code}</code> || <code>Put</code>
|}
|}


== Endpunkt-Skript 1: <code>GET /orders</code> (Liste) ==
Jeder Endpunkt hat sein eigenes Skript und seine eigene Berechtigung. Regeln für Templates und Vorrang: [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]].


<syntaxhighlight lang="pascal">
== Gemeinsamer Helfer ==
// Hilfsfunktion: die FELDER eines Auftrags. Der Helfer bekommt den Writer und
Die Skripte der Liste und des einzelnen Auftrags schreiben dieselben Felder. Der Helfer bekommt den Writer und schreibt in das Objekt, das gerade offen ist: einmal in einen Listeneintrag, einmal in die Wurzel der Antwort. Er steht in beiden Skripten oder einmal in einer ausgelagerten Bibliothek, siehe [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]].
// schreibt in das Objekt, das der Aufrufer schon geoeffnet hat - so laesst sich
 
// derselbe Auftrag einmal als Listeneintrag und einmal als ganze Antwort
<syntaxhighlight lang="delphi">
// ausgeben, ohne den Code zu verdoppeln.
// Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geöffnet hat
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TqSQL;
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TxFQuery;
                       const cOffset: string);
                       const cOffset: string);
begin
begin
Zeile 49: Zeile 46:
     oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
     oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
     oWriter.Str ('status', qOrder.A2C('au_status'));
     oWriter.Str ('status', qOrder.A2C('au_status'));
     // ISO-8601 mit Offset - siehe den Hinweis unter der Liste.
     // Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
     oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
     oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;
end;
</syntaxhighlight>


== Endpunkt-Skript 1: <code>GET /orders</code> ==
<syntaxhighlight lang="delphi">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql  : string;
var cSql  : string;
     qData  : TqSQL;
     qData  : TxFQuery;
     cOffset: string;
     cOffset: string;
begin
begin
     cOffset := oReader.Offset();
     cOffset := oReader.Offset();
     // Die Antwort ist eine nackte Liste - RootArr vor dem ersten Eintrag.
 
    // Findet die Abfrage nichts, ist es eine leere Liste und kein leeres
     // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
    // Objekt: deshalb steht der Aufruf VOR der Abfrage.
     oWriter.RootArr();
     oWriter.RootArr();


     cSql := 'SELECT * FROM auftraege' +
     cSql := 'SELECT * FROM AUFTRAEGE' +
             ' WHERE au_status <> ' + DB_SQLVal('9') +
             ' WHERE au_status <> ' + DB_SqlVal('9', 'C') +
             ' ORDER BY au_nr';
             ' ORDER BY au_nr';
     if (DB_SOpen(oDB, cSql, qData)) then begin
     if (DB_SOpen(oDB, cSql, qData)) then begin
Zeile 79: Zeile 78:
</syntaxhighlight>
</syntaxhighlight>


== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> (Einzel) ==
== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> ==
 
<syntaxhighlight lang="delphi">
<syntaxhighlight lang="pascal">
// Derselbe Helfer wie im Listen-Skript - hier schreibt er in die WURZEL, weil
// der Auftrag selbst die Antwort ist. Eine eigene Fehlerfunktion braucht es
// nicht mehr: oWriter.Error setzt Statuscode, code, message, uid und traceId.
// Derselbe Helfer wie im Listen-Skript - hier schreibt er in die WURZEL,
// weil der Auftrag selbst die Antwort ist.
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TqSQL;
                      const cOffset: string);
begin
    oWriter.Str ('uid'  , qOrder.A2UID());
    oWriter.Str ('nr'    , qOrder.A2C('au_nr'));
    oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
    oWriter.Str ('status', qOrder.A2C('au_status'));
    oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;
 
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid    : string;
var cUid    : string;
     cSql    : string;
     cSql    : string;
     qData    : TqSQL;
     qData    : TxFQuery;
     lGefunden: Boolean;
     lGefunden: Boolean;
     cOffset  : string;
     cOffset  : string;
begin
begin
     // Pfad-Parameter aus /orders/{uid}
     // Der Wert kommt aus der URL des Clients. DB_SqlVal schützt die Abfrage,
    // ein unbekannter Wert führt zu 404.
     cUid    := oReader.Path('uid');
     cUid    := oReader.Path('uid');
     cOffset := oReader.Offset();
     cOffset := oReader.Offset();
    if (cUid = '') then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" fehlt');
        exit;
    end;


     lGefunden := false;
     lGefunden := false;
     cSql := 'SELECT * FROM auftraege WHERE sys_uid = ' + DB_SQLVal(cUid);
     cSql := 'SELECT * FROM AUFTRAEGE WHERE sys_uid = ' + DB_SqlVal(cUid, 'C');
     if (DB_SOpen(oDB, cSql, qData)) then begin
     if (DB_SOpen(oDB, cSql, qData)) then begin
         if (not qData.EoF) then begin
         if (not qData.EoF) then begin
Zeile 129: Zeile 109:


== Endpunkt-Skript 3: <code>PUT /orders/{uid}/modules/{code}</code> ==
== Endpunkt-Skript 3: <code>PUT /orders/{uid}/modules/{code}</code> ==
<code>PUT</code> läuft in einer Datenbanktransaktion. Endet das Skript mit einem Status ab 400, nimmt der Server alle Änderungen zurück.


<syntaxhighlight lang="pascal">
<syntaxhighlight lang="delphi">
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid  : string;
var cUid  : string;
Zeile 136: Zeile 117:
     cStatus: string;
     cStatus: string;
     cSql  : string;
     cSql  : string;
     qChk  : TqSQL;
     qChk  : TxFQuery;
     xMod   : TqSQL;
     qMod   : TqSQL;
     cModUid: string;
     cModUid: string;
     lOk    : Boolean;
     lOk    : Boolean;
Zeile 144: Zeile 125:
     cUid  := oReader.Path('uid');
     cUid  := oReader.Path('uid');
     cCode := oReader.Path('code');
     cCode := oReader.Path('code');
    if (cUid = '') or (cCode = '') then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Pfad-Parameter "uid" oder "code" fehlt');
        exit;
    end;


     // Nutzdaten kommen aus dem JSON-Body. Der Rueckgabewert sagt, ob das Feld
     // Nutzdaten aus dem JSON-Körper
    // ueberhaupt gesendet wurde - eine eigene Hilfsfunktion dafuer braucht es
    // nicht mehr.
     cStatus := '';
     cStatus := '';
     oReader.Str('status', cStatus);
     oReader.Str('status', cStatus);
     if (cStatus = '') then begin
     if (Empty(cStatus)) then begin
         oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
         oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
         exit;
         exit;
     end;
     end;


     // Existenzpruefung - und zugleich der Schreib-Index. Ein SELECT auf die
     // Eine Abfrage auf die sys_uid liefert Existenzprüfung und Schreib-Index
    // sys_uid liefert beides; ein 'SELECT *' waere hier verschenkte Arbeit.
     cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' +
     cSql := 'SELECT sys_uid FROM auftrag_module' +
             ' WHERE am_auftrag = ' + DB_SqlVal(cUid, 'C') +
             ' WHERE am_auftrag = ' + DB_SQLVal(cUid) +
             '   AND am_code = '   + DB_SqlVal(cCode, 'C') + ' LIMIT 1';
             ' AND am_code = ' + DB_SQLVal(cCode) + ' LIMIT 1';
     cModUid := '';
     cModUid := '';
     if (DB_SOpen(oDB, cSql, qChk)) then begin
     if (DB_SOpen(oDB, cSql, qChk)) then begin
Zeile 172: Zeile 146:
     DB_Close(qChk);
     DB_Close(qChk);


     if (cModUid = '') then begin
     if (Empty(cModUid)) then begin
         oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden');
         oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden');
         exit;
         exit;
     end;
     end;


     // Update
     // Ändern: qSqlInit mit sys_uid als Schreib-Index
    // Der Satz wird ueber seine sys_uid geschrieben - qSqlRead waere hier
     qMod := qSqlInit(oDB, 'AUFTRAG_MODULE');
     // ein zusaetzlicher Lesezugriff, und ein unveraenderter Wert wuerde gar
     qMod.qSet('sys_uid'  , cModUid);
    // kein Write erzeugen (SaveData liefert dann False).
     qMod.qSet('am_status', cStatus);
    xMod := qSqlInit(oDB, 'auftrag_module');
     // Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
     xMod.qSet('sys_uid'  , cModUid);
     lOk := qMod.SaveData(UPDATE_RECORD);
     xMod.qSet('am_status', cStatus);
     qSqlFree(qMod);
     // Rueckgabewert auswerten - ein Schreibfehler wirft keine Exception
     lOk := xMod.SaveData(UPDATE_RECORD);
     qSqlFree(xMod);


     if (not lOk) then begin
     if (not lOk) then begin
Zeile 198: Zeile 169:


== Test mit curl ==
== Test mit curl ==
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Liste
# Liste
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    https://obs.example.com/orders


# Einzelner Auftrag (uid als Pfad-Parameter)
# Einzelner Auftrag (uid als Pfad-Parameter)
curl -H "apikey: GEHEIM123" https://api.meinserver.de/orders/4711
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    https://obs.example.com/orders/4711


# Modul-Status aendern (uid + code als Pfad-Parameter, status im Body)
# Modul-Status ändern (uid und code als Pfad-Parameter, status im Körper)
curl -X PUT \
curl -X PUT \
     -H "apikey: GEHEIM123" \
     -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Idempotency-Key: 5b9e2c7a-1f43-4d8e-9a60-c3f1d7e2b845" \
     -H "Content-Type: application/json" \
     -H "Content-Type: application/json" \
     -d '{"status":"21"}' \
     -d '{"status":"21"}' \
     https://api.meinserver.de/orders/4711/modules/A1
     https://obs.example.com/orders/4711/modules/A1
</syntaxhighlight>
</syntaxhighlight>


== Was dieses Beispiel zeigt ==
Der <code>Idempotency-Key</code> ist bei <code>PUT</code> Pflicht. Ein wiederholter Aufruf mit demselben Schlüssel und demselben Körper liefert die gespeicherte Antwort mit dem Header <code>Idempotent-Replay: true</code>. Regeln: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].


* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkt-Einträge mit eigenem Skript und eigener Berechtigung.
== Was zeigt das Beispiel? ==
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript mit <code>oReader.Path('name')</code> gelesen.
* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkte mit eigenem Skript und eigener Berechtigung.
* Reihenfolge der Skript-Parameter: '''<code>oReader</code> zuerst, <code>oWriter</code> danach'''.
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript mit <code>oReader.Path('name')</code> gelesen. Der Wert kommt vom Client und wird wie jede Eingabe geprüft.
* '''Ein Helfer bekommt den Writer''' und schreibt an der Stelle hinein, an der er gerufen wird. Derselbe <code>_OrderFelder</code> bedient den Listeneintrag und die Einzelantwort - einmal in einem <code>ObjBegin('')</code>, einmal in der Wurzel.
* Die Skriptmethoden haben die Parameter <code>(oReader: TxRestReader; oWriter: TxRestWriter)</code>, Reader zuerst.
* Präzedenz: ein statisches Segment (z.&nbsp;B. <code>/orders/summary</code>) hätte Vorrang vor <code>/orders/{uid}</code>.
* '''Ein Helfer bekommt den Writer''' und schreibt an der Stelle hinein, an der er aufgerufen wird. Derselbe <code>_OrderFelder</code> bedient den Listeneintrag und die Einzelantwort.
* '''Vorrang:''' Ein statisches Segment, z.B. <code>/orders/summary</code>, hätte Vorrang vor <code>/orders/{uid}</code>.
* '''Schreibender Aufruf''' mit <code>Idempotency-Key</code> und Transaktion.


== Siehe auch ==
== Siehe auch ==
 
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[/OBS/Kostenpflichtige_Module/RESTServer/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper|Beispiel 3: Datensatz anlegen mit JSON-Body]]

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

Pfad-Parameter

Dieses Beispiel zeigt das Routing über Pfad-Templates mit Platzhaltern. So entstehen sprechende Adressen, wie sie Entwickler von modernen REST-Schnittstellen erwarten. Eine Auftrags-Ressource wird über drei Endpunkte abgebildet:

Methode und Pfad Zweck
GET /orders Liste aller offenen Aufträge
GET /orders/{uid} Einzelner Auftrag über seine UID
PUT /orders/{uid}/modules/{code} Status eines Auftrags-Moduls ändern

Die Platzhalter {uid} und {code} stehen im Skript über oReader.Path('uid') bzw. oReader.Path('code') bereit.

Einrichtung in OBS

  • Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
  • Zugang: Orders-Client mit API-Key, berechtigt für die drei Endpunkte
  • Endpunkte, alle mit Server Public-API:
Pfad-Template Skriptmethode
/orders Get (Liste)
/orders/{uid} Get (einzelner Auftrag)
/orders/{uid}/modules/{code} Put

Jeder Endpunkt hat sein eigenes Skript und seine eigene Berechtigung. Regeln für Templates und Vorrang: Endpunkte.

Gemeinsamer Helfer

Die Skripte der Liste und des einzelnen Auftrags schreiben dieselben Felder. Der Helfer bekommt den Writer und schreibt in das Objekt, das gerade offen ist: einmal in einen Listeneintrag, einmal in die Wurzel der Antwort. Er steht in beiden Skripten oder einmal in einer ausgelagerten Bibliothek, siehe Scripting.

// Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geöffnet hat
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TxFQuery;
                       const cOffset: string);
begin
    oWriter.Str ('uid'   , qOrder.A2UID());
    oWriter.Str ('nr'    , qOrder.A2C('au_nr'));
    oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
    oWriter.Str ('status', qOrder.A2C('au_status'));
    // Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
    oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;

Endpunkt-Skript 1: GET /orders

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql   : string;
    qData  : TxFQuery;
    cOffset: string;
begin
    cOffset := oReader.Offset();

    // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
    oWriter.RootArr();

    cSql := 'SELECT * FROM AUFTRAEGE' +
            ' WHERE au_status <> ' + DB_SqlVal('9', 'C') +
            ' ORDER BY au_nr';
    if (DB_SOpen(oDB, cSql, qData)) then begin
        while (not qData.EoF) do begin
            oWriter.ObjBegin('');
                _OrderFelder(oWriter, qData, cOffset);
            oWriter.ObjEnd;
            qData.Next();
        end;
    end;
    DB_Close(qData);
end;

Endpunkt-Skript 2: GET /orders/{uid}

procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid     : string;
    cSql     : string;
    qData    : TxFQuery;
    lGefunden: Boolean;
    cOffset  : string;
begin
    // Der Wert kommt aus der URL des Clients. DB_SqlVal schützt die Abfrage,
    // ein unbekannter Wert führt zu 404.
    cUid    := oReader.Path('uid');
    cOffset := oReader.Offset();

    lGefunden := false;
    cSql := 'SELECT * FROM AUFTRAEGE WHERE sys_uid = ' + DB_SqlVal(cUid, 'C');
    if (DB_SOpen(oDB, cSql, qData)) then begin
        if (not qData.EoF) then begin
            _OrderFelder(oWriter, qData, cOffset);
            lGefunden := true;
        end;
    end;
    DB_Close(qData);

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

Endpunkt-Skript 3: PUT /orders/{uid}/modules/{code}

PUT läuft in einer Datenbanktransaktion. Endet das Skript mit einem Status ab 400, nimmt der Server alle Änderungen zurück.

procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid   : string;
    cCode  : string;
    cStatus: string;
    cSql   : string;
    qChk   : TxFQuery;
    qMod   : TqSQL;
    cModUid: string;
    lOk    : Boolean;
begin
    // Beide Pfad-Parameter
    cUid  := oReader.Path('uid');
    cCode := oReader.Path('code');

    // Nutzdaten aus dem JSON-Körper
    cStatus := '';
    oReader.Str('status', cStatus);
    if (Empty(cStatus)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "status" fehlt');
        exit;
    end;

    // Eine Abfrage auf die sys_uid liefert Existenzprüfung und Schreib-Index
    cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' +
            ' WHERE am_auftrag = ' + DB_SqlVal(cUid, 'C') +
            '   AND am_code = '    + DB_SqlVal(cCode, 'C') + ' LIMIT 1';
    cModUid := '';
    if (DB_SOpen(oDB, cSql, qChk)) then begin
        if (not qChk.EoF) then begin
            cModUid := qChk.A2UID();
        end;
    end;
    DB_Close(qChk);

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

    // Ändern: qSqlInit mit sys_uid als Schreib-Index
    qMod := qSqlInit(oDB, 'AUFTRAG_MODULE');
    qMod.qSet('sys_uid'  , cModUid);
    qMod.qSet('am_status', cStatus);
    // Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
    lOk := qMod.SaveData(UPDATE_RECORD);
    qSqlFree(qMod);

    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Status konnte nicht gespeichert werden');
        exit;
    end;

    oWriter.Str('status', 'ok');
end;

Test mit curl

# Liste
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     https://obs.example.com/orders

# Einzelner Auftrag (uid als Pfad-Parameter)
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     https://obs.example.com/orders/4711

# Modul-Status ändern (uid und code als Pfad-Parameter, status im Körper)
curl -X PUT \
     -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     -H "Idempotency-Key: 5b9e2c7a-1f43-4d8e-9a60-c3f1d7e2b845" \
     -H "Content-Type: application/json" \
     -d '{"status":"21"}' \
     https://obs.example.com/orders/4711/modules/A1

Der Idempotency-Key ist bei PUT Pflicht. Ein wiederholter Aufruf mit demselben Schlüssel und demselben Körper liefert die gespeicherte Antwort mit dem Header Idempotent-Replay: true. Regeln: HTTP-Schnittstelle.

Was zeigt das Beispiel?

  • Eine Ressource, mehrere Pfad-Formen über getrennte Endpunkte mit eigenem Skript und eigener Berechtigung.
  • Pfad-Parameter werden über {name} im Template erfasst und im Skript mit oReader.Path('name') gelesen. Der Wert kommt vom Client und wird wie jede Eingabe geprüft.
  • Die Skriptmethoden haben die Parameter (oReader: TxRestReader; oWriter: TxRestWriter), Reader zuerst.
  • Ein Helfer bekommt den Writer und schreibt an der Stelle hinein, an der er aufgerufen wird. Derselbe _OrderFelder bedient den Listeneintrag und die Einzelantwort.
  • Vorrang: Ein statisches Segment, z.B. /orders/summary, hätte Vorrang vor /orders/{uid}.
  • Schreibender Aufruf mit Idempotency-Key und Transaktion.

Siehe auch