OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter: Unterschied zwischen den Versionen
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…“ |
Ü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}} | ||
= | {{Seitentyp|Referenz}} | ||
= Pfad-Parameter = | |||
Dieses Beispiel zeigt das '''Pfad- | 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 | ! 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 | | <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 | 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> | |||
<code> | |||
== Einrichtung in OBS == | == Einrichtung in OBS == | ||
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443 | |||
* '''Server-Profil:''' | * '''Zugang:''' ''Orders-Client'' mit '''API-Key''', berechtigt für die drei Endpunkte | ||
* '''Zugang:''' ''Orders-Client'' mit API-Key, | * '''Endpunkte''', alle mit '''Server''' ''Public-API'': | ||
* '''Endpunkte''' | |||
{| class="wikitable" | {| class="wikitable" | ||
! Pfad-Template !! Skriptmethode | |||
|- | |- | ||
| <code>/orders</code> || <code>Get</code> (Liste) | |||
|- | |- | ||
| <code>/orders/{uid}</code> || <code>Get</code> (einzelner Auftrag) | |||
|- | |- | ||
| <code>/orders/{uid}/modules/{code}</code> || <code>Put</code> | |||
|} | |} | ||
Jeder Endpunkt hat sein eigenes Skript und seine eigene Berechtigung. Regeln für Templates und Vorrang: [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|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 [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]. | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
// | // Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geöffnet hat | ||
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: TxFQuery; | |||
const cOffset: string); | |||
begin | 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; | end; | ||
</syntaxhighlight> | |||
== Endpunkt-Skript 1: <code>GET /orders</code> == | |||
var cSql : string; | <syntaxhighlight lang="delphi"> | ||
qData: | procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | ||
var cSql : string; | |||
qData : TxFQuery; | |||
cOffset: string; | |||
begin | begin | ||
cOffset := oReader.Offset(); | |||
cSql := 'SELECT * FROM | // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste | ||
' WHERE au_status <> ' + | oWriter.RootArr(); | ||
cSql := 'SELECT * FROM AUFTRAEGE' + | |||
' WHERE au_status <> ' + DB_SqlVal('9', 'C') + | |||
' ORDER BY au_nr'; | ' ORDER BY au_nr'; | ||
if (DB_SOpen( | if (DB_SOpen(oDB, cSql, qData)) then begin | ||
while (not qData.EoF) do begin | while (not qData.EoF) do begin | ||
oWriter.ObjBegin(''); | |||
_OrderFelder(oWriter, qData, cOffset); | |||
oWriter.ObjEnd; | |||
qData.Next(); | qData.Next(); | ||
end; | end; | ||
end; | end; | ||
DB_Close(qData); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Endpunkt-Skript 2: <code>GET /orders/{uid}</code> | == Endpunkt-Skript 2: <code>GET /orders/{uid}</code> == | ||
<syntaxhighlight lang="delphi"> | |||
<syntaxhighlight lang=" | procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | ||
var cUid : string; | |||
cSql : string; | |||
qData : TxFQuery; | |||
lGefunden: Boolean; | |||
cOffset : string; | |||
begin | 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'); | |||
cSql : | if (DB_SOpen(oDB, cSql, qData)) then begin | ||
if (not qData.EoF) then begin | |||
_OrderFelder(oWriter, qData, cOffset); | |||
lGefunden := true; | |||
end; | |||
if ( | |||
end; | end; | ||
DB_Close(qData); | |||
if (not lGefunden) then begin | |||
if | oWriter.Error(404, 'NOT_FOUND', '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=" | <syntaxhighlight lang="delphi"> | ||
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 : | qChk : TxFQuery; | ||
qMod : TqSQL; | |||
cModUid: string; | |||
lOk : Boolean; | |||
begin | begin | ||
// Beide Pfad-Parameter | // Beide Pfad-Parameter | ||
cUid := | cUid := oReader.Path('uid'); | ||
cCode := | 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; | exit; | ||
end; | end; | ||
// | // Eine Abfrage auf die sys_uid liefert Existenzprüfung und Schreib-Index | ||
cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' + | |||
if ( | ' 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; | end; | ||
if ( | DB_Close(qChk); | ||
if (Empty(cModUid)) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Modul nicht gefunden'); | |||
exit; | exit; | ||
end; | end; | ||
// | // Ändern: qSqlInit mit sys_uid als Schreib-Index | ||
qMod := qSqlInit(oDB, 'AUFTRAG_MODULE'); | |||
qMod.qSet('sys_uid' , cModUid); | |||
qMod.qSet('am_status', cStatus); | |||
if (not | // 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; | exit; | ||
end; | end; | ||
oWriter.Str('status', 'ok'); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Test mit curl == | == Test mit curl == | ||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
# Liste | # Liste | ||
curl -H "apikey: | 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: | curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | ||
https://obs.example.com/orders/4711 | |||
# Modul-Status | # Modul-Status ändern (uid und code als Pfad-Parameter, status im Körper) | ||
curl -X PUT \ | curl -X PUT \ | ||
-H "apikey: | -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:// | https://obs.example.com/orders/4711/modules/A1 | ||
</syntaxhighlight> | </syntaxhighlight> | ||
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 | == Was zeigt das Beispiel? == | ||
* '''Pfad-Parameter''' werden über <code>{name}</code> im Template erfasst und im Skript | * '''Eine Ressource, mehrere Pfad-Formen''' über getrennte Endpunkte mit eigenem Skript und eigener Berechtigung. | ||
* | * '''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. | ||
* 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/REST-Server/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 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.