Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter

Aus OBS Wiki
Version vom 17. November 2026, 07:14 Uhr von MINERVA-Rademacker (Diskussion | Beiträge) (MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Beispiel4 nach OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel))

Beispiel 4 – Pfad-Parameter (REST-Routing über Templates)

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 geoeffnet 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 schuetzt die Abfrage,
    // ein unbekannter Wert fuehrt 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-Koerper
    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 Existenzpruefung 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;

    // Aendern: 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 Rueckgabewert 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 aendern (uid und code als Pfad-Parameter, status im Koerper)
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