OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter
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 mitoReader.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
_OrderFelderbedient den Listeneintrag und die Einzelantwort. - Vorrang: Ein statisches Segment, z.B.
/orders/summary, hätte Vorrang vor/orders/{uid}. - Schreibender Aufruf mit
Idempotency-Keyund Transaktion.