Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Die Seite wurde neu angelegt: „{{Kostenpflichtige Module}} = Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) = Dieses Beispiel zeigt das '''Pfad-Template-Routing''' mit Platzhaltern. Eine Auftrags-Ressource wird über drei Endpunkte abgebildet: {| class="wikitable" ! Methode + Pfad !! Zweck |- | <code>GET /orders</code> || Liste aller offenen Aufträge |- | <code>GET /orders/{uid}</code> || Einzelner Auftrag per UID |- | <code>PUT /orders/{uid}/modules/{code}</code> || S…“
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(8 dazwischenliegende Versionen von 2 Benutzern 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>oParams.Values['_OBS_PATH_uid']</code> bzw.
<code>oParams.Values['_OBS_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>
|}
|}


{{Hinweis|Das Feld '''Endpunkt''' (<code>re_endpoint</code>) ist nur informativ –
Jeder Endpunkt hat sein eigenes Skript und seine eigene Berechtigung. Regeln für Templates und Vorrang: [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]].
geroutet wird ausschließlich über das '''Pfad-Template'''. Die Berechtigung wird
pro Eintrag vergeben, sodass z.&nbsp;B. das ändernde <code>PUT</code> einem anderen
Zugang vorbehalten werden kann als die lesenden <code>GET</code>-Endpunkte.}}


== Endpunkt-Skript 1: <code>GET /orders</code> (Liste) ==
== 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 [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]].


<syntaxhighlight lang="pascal">
<syntaxhighlight lang="delphi">
// Hilfsfunktion: ein Auftrag als JSON-Objekt
// Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geöffnet hat
function _OrderAsJSON(qOrder: TqSQL): TJSONObject;
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TxFQuery;
                      const cOffset: string);
begin
begin
     result := TJSONObject.Create();
     oWriter.Str ('uid'   , qOrder.A2UID());
    result.AddPair('uid'     , qOrder.A2UID());
     oWriter.Str ('nr'   , qOrder.A2C('au_nr'));
     result.AddPair('nr'       , qOrder.A2C('au_nr'));
     oWriter.Str ('kunde' , qOrder.A2C('au_kunde'));
     result.AddPair('kunde'   , qOrder.A2C('au_kunde'));
     oWriter.Str ('status', qOrder.A2C('au_status'));
     result.AddPair('status'   , qOrder.A2C('au_status'));
     // Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
     result.AddPair('aenderung', DTToSQL(qOrder.A2D('au_aend_dat')));
    oWriter.StrN('aenderung', RestIsoFromDate(qOrder.A2D('au_aend_dat'), cOffset));
end;
end;
</syntaxhighlight>


function Get(oParams: TStrings; oBody: TJSONObject): string;
== Endpunkt-Skript 1: <code>GET /orders</code> ==
var cSql : string;
<syntaxhighlight lang="delphi">
     qData: TqSQL;
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
     oArr : TJSONArray;
var cSql   : string;
     qData : TxFQuery;
     cOffset: string;
begin
begin
     oArr := TJSONArray.Create();
     cOffset := oReader.Offset();


     cSql := 'SELECT * FROM auftraege' +
    // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
             ' WHERE au_status <> ' + DB_SQLVal('9') +
    oWriter.RootArr();
 
     cSql := 'SELECT * FROM AUFTRAEGE' +
             ' WHERE au_status <> ' + DB_SqlVal('9', 'C') +
             ' ORDER BY au_nr';
             ' ORDER BY au_nr';
     if (DB_SOpen('Y00ORDLST1', oDB, cSql, qData)) then begin
     if (DB_SOpen(oDB, cSql, qData)) then begin
         while (not qData.EoF) do begin
         while (not qData.EoF) do begin
             oArr.Add(_OrderAsJSON(qData));
             oWriter.ObjBegin('');
                _OrderFelder(oWriter, qData, cOffset);
            oWriter.ObjEnd;
             qData.Next();
             qData.Next();
         end;
         end;
     end;
     end;
 
     DB_Close(qData);
     result := oArr.ToJSON();
end;
end;
</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">
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
function _OrderAsJSON(qOrder: TqSQL): TJSONObject;
var cUid    : string;
    cSql    : string;
    qData    : TxFQuery;
    lGefunden: Boolean;
    cOffset  : string;
begin
begin
     result := TJSONObject.Create();
     // Der Wert kommt aus der URL des Clients. DB_SqlVal schützt die Abfrage,
    result.AddPair('uid'      , qOrder.A2UID());
     // ein unbekannter Wert führt zu 404.
     result.AddPair('nr'      , qOrder.A2C('au_nr'));
     cUid   := oReader.Path('uid');
     result.AddPair('kunde'   , qOrder.A2C('au_kunde'));
     cOffset := oReader.Offset();
     result.AddPair('status'  , qOrder.A2C('au_status'));
    result.AddPair('aenderung', DTToSQL(qOrder.A2D('au_aend_dat')));
end;


function Get(oParams: TStrings; oBody: TJSONObject): string;
    lGefunden := false;
var cUid : string;
     cSql := 'SELECT * FROM AUFTRAEGE WHERE sys_uid = ' + DB_SqlVal(cUid, 'C');
     cSql : string;
     if (DB_SOpen(oDB, cSql, qData)) then begin
    qData: TqSQL;
         if (not qData.EoF) then begin
begin
            _OrderFelder(oWriter, qData, cOffset);
    // Pfad-Parameter aus /orders/{uid}
            lGefunden := true;
    cUid := oParams.Values['_OBS_PATH_uid'];
         end;
     if (cUid = '') then begin
         result := '{"error":"uid fehlt"}';
         exit;
     end;
     end;
    DB_Close(qData);


    cSql := 'SELECT * FROM auftraege WHERE sys_uid = ' + DB_SQLVal(cUid);
     if (not lGefunden) then begin
     if (DB_SOpen('Y00ORDGET1', oDB, cSql, qData)) and (not qData.EoF) then begin
         oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
         result := _OrderAsJSON(qData).ToJSON();
    end else begin
        result := '{"error":"Auftrag nicht gefunden"}';
     end;
     end;
end;
end;
Zeile 110: 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">
function Put(oParams: TStrings; oBody: TJSONObject): string;
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid  : string;
var cUid  : string;
     cCode  : string;
     cCode  : string;
     cStatus: string;
     cStatus: string;
     cSql  : string;
     cSql  : string;
     qChk  : TqSQL;
     qChk  : TxFQuery;
     xMod   : TqSQL;
     qMod   : TqSQL;
    cModUid: string;
    lOk    : Boolean;
begin
begin
     // Beide Pfad-Parameter
     // Beide Pfad-Parameter
     cUid  := oParams.Values['_OBS_PATH_uid'];
     cUid  := oReader.Path('uid');
     cCode := oParams.Values['_OBS_PATH_code'];
     cCode := oReader.Path('code');
     if (cUid = '') or (cCode = '') then begin
 
         result := '{"error":"uid oder code fehlt"}';
     // 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;
         exit;
     end;
     end;


     // Nutzdaten kommen aus dem JSON-Body
     // Eine Abfrage auf die sys_uid liefert Existenzprüfung und Schreib-Index
     cStatus := '';
     cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' +
     if (Assigned(oBody)) then begin
            ' WHERE am_auftrag = ' + DB_SqlVal(cUid, 'C') +
         oBody.TryGetValue<string>('status', cStatus);
            '  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;
     end;
     if (cStatus = '') then begin
    DB_Close(qChk);
         result := '{"error":"status fehlt"}';
 
     if (Empty(cModUid)) then begin
         oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden');
         exit;
         exit;
     end;
     end;


     // Existenzpruefung
     // Ändern: qSqlInit mit sys_uid als Schreib-Index
     cSql := 'SELECT * FROM auftrag_module' +
     qMod := qSqlInit(oDB, 'AUFTRAG_MODULE');
            ' WHERE am_auftrag = ' + DB_SQLVal(cUid) +
    qMod.qSet('sys_uid' , cModUid);
            ' AND am_code = ' + DB_SQLVal(cCode);
    qMod.qSet('am_status', cStatus);
     if (not DB_SOpen('Y00ORDMOD1', oDB, cSql, qChk)) or (qChk.EoF) then begin
    // Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
         result := '{"error":"Modul nicht gefunden"}';
    lOk := qMod.SaveData(UPDATE_RECORD);
    qSqlFree(qMod);
 
     if (not lOk) then begin
         oWriter.Error(500, 'INTERNAL_ERROR', 'Status konnte nicht gespeichert werden');
         exit;
         exit;
     end;
     end;


     // Update
     oWriter.Str('status', 'ok');
    xMod := qSqlRead('Y00ORDMOD2', oDB, 'auftrag_module',
                    'am_auftrag = ' + DB_SQLVal(cUid) +
                    ' AND am_code = ' + DB_SQLVal(cCode));
    xMod.qSet('am_status', cStatus);
    xMod.SaveData(UPDATE_RECORD);
    qSqlFree(xMod);
 
    result := '{"status":"ok"}';
end;
end;
</syntaxhighlight>
</syntaxhighlight>


== 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 als <code>oParams.Values['_OBS_PATH_name']</code> gelesen.
* '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkte mit eigenem Skript und eigener Berechtigung.
* Reihenfolge der Skript-Parameter: '''<code>oParams</code> zuerst, <code>oBody</code> danach''' (umgekehrt zur internen Dispatch-Reihenfolge).
* '''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.
* Präzedenz: ein statisches Segment (z.&nbsp;B. <code>/orders/summary</code>) hätte Vorrang vor <code>/orders/{uid}</code>.
* Die Skriptmethoden haben die Parameter <code>(oReader: TxRestReader; oWriter: TxRestWriter)</code>, Reader zuerst.
* '''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