OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter: Unterschied zwischen den Versionen
Vorlage:-Praefix; zwei Links ohne fuehrenden Schraegstrich korrigiert [Volltext ersetzt] |
TxFQuery statt TqSQL, Helfer _OrderFelder nur einmal, Idempotency-Key beim PUT, Platzhalter-Key/Host, Links ohne Unterstrich, Abschnitt „Was zeigt das Beispiel?“ [Volltext ersetzt] |
||
| Zeile 1: | Zeile 1: | ||
{{Vorlage:Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Referenz}} | |||
= Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) = | = Beispiel 4 – Pfad-Parameter (REST-Routing über Templates) = | ||
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>oReader.Path('uid')</code> bzw. <code>oReader.Path('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/RESTServer/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/RESTServer/Scripting|Scripting]]. | |||
<syntaxhighlight lang="delphi"> | |||
// | // Schreibt die Felder eines Auftrags in das Objekt, das der Aufrufer geoeffnet hat | ||
procedure _OrderFelder(oWriter: TxRestWriter; qOrder: | 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 | // 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 : | qData : TxFQuery; | ||
cOffset: string; | cOffset: string; | ||
begin | begin | ||
cOffset := oReader.Offset(); | cOffset := oReader.Offset(); | ||
// | |||
// Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste | |||
oWriter.RootArr(); | oWriter.RootArr(); | ||
cSql := 'SELECT * FROM | cSql := 'SELECT * FROM AUFTRAEGE' + | ||
' WHERE au_status <> ' + | ' 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> | == Endpunkt-Skript 2: <code>GET /orders/{uid}</code> == | ||
<syntaxhighlight lang="delphi"> | |||
<syntaxhighlight lang=" | |||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | ||
var cUid : string; | var cUid : string; | ||
cSql : string; | cSql : string; | ||
qData : | qData : TxFQuery; | ||
lGefunden: Boolean; | lGefunden: Boolean; | ||
cOffset : string; | cOffset : string; | ||
begin | begin | ||
// | // Der Wert kommt aus der URL des Clients. DB_SqlVal schuetzt die Abfrage, | ||
// ein unbekannter Wert fuehrt zu 404. | |||
cUid := oReader.Path('uid'); | cUid := oReader.Path('uid'); | ||
cOffset := oReader.Offset(); | cOffset := oReader.Offset(); | ||
lGefunden := false; | lGefunden := false; | ||
cSql := 'SELECT * FROM | 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=" | <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 : | qChk : TxFQuery; | ||
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'); | ||
// Nutzdaten | // Nutzdaten aus dem JSON-Koerper | ||
cStatus := ''; | cStatus := ''; | ||
oReader.Str('status', cStatus); | oReader.Str('status', cStatus); | ||
if (cStatus | 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 | // Eine Abfrage auf die sys_uid liefert Existenzpruefung und Schreib-Index | ||
cSql := 'SELECT sys_uid FROM AUFTRAG_MODULE' + | |||
cSql := 'SELECT sys_uid FROM | ' WHERE am_auftrag = ' + DB_SqlVal(cUid, 'C') + | ||
' WHERE am_auftrag = ' + | ' AND am_code = ' + DB_SqlVal(cCode, 'C') + ' LIMIT 1'; | ||
' AND am_code = ' + | |||
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 | 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; | ||
// | // 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); | |||
// | |||
lOk := | |||
qSqlFree( | |||
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: | 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 aendern (uid | # Modul-Status aendern (uid und code als Pfad-Parameter, status im Koerper) | ||
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/RESTServer/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 mit <code>oReader.Path('name')</code> gelesen. | * '''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. | ||
* '''Ein Helfer bekommt den Writer''' und schreibt an der Stelle hinein, an der er | * 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/RESTServer/Endpunkte|Endpunkte]] | |||
* [[OBS/ | * [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] | ||
* [[OBS/ | * [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]] | ||
* [[OBS/Kostenpflichtige Module/RESTServer/Beispiel3|Beispiel 3: Datensatz anlegen mit JSON-Body]] | |||
Version vom 17. November 2026, 06:59 Uhr
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.