OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz: Unterschied zwischen den Versionen
Keine Bearbeitungszusammenfassung |
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt] |
||
| (4 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
{{Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Referenz}} | |||
= Schreibzugriff mit Statuscodes, ETag und Idempotenz = | |||
Dieses Beispiel zeigt schreibende Endpunkte für eine mobile App, wie sie im Außendienst täglich im Einsatz sind: Aufträge werden mit echten HTTP-Statuscodes geändert, gleichzeitige Änderungen über <code>ETag</code> und <code>If-Match</code> erkannt und doppelte Sendungen über den <code>Idempotency-Key</code> abgefangen. Die Anmeldung nutzt JWT mit eigenen Claims für Mandant und Rollen und mit Refresh-Token. | |||
Die Hilfsfunktionen im Code (<code>PasswortPasst</code>, <code>TechnikerMandant</code>, <code>TechnikerRollen</code>, <code>TechnikerAktiv</code>, <code>AuftragLesen</code>, <code>AuftragVersion</code>, <code>AuftragSpeichern</code>, <code>MaterialAnlegen</code>, <code>ArtikelPreis</code>, <code>PushRegistrierungLoeschen</code>) stehen für Ihre Fachlogik. Sie sind kein Teil des REST-Servers. | |||
==Einrichtung in OBS== | == Einrichtung in OBS == | ||
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443 | |||
* '''Server-Profil:''' | |||
* '''Zugang:''' ''Mobile-App'' | * '''Zugang:''' ''Mobile-App'' | ||
** API-Key: | ** '''API-Key:''' vom System erzeugt | ||
** JWT | ** Haken '''JWT-Authentifizierung''' gesetzt, '''Endpunkt''' <code>/auth</code>, '''Secret-Key''' zufällig, '''Lebenszeit (Min)''' ''60'' | ||
* '''Endpunkte''' | * '''Endpunkte''', alle mit '''Server''' ''Public-API'': | ||
** | ** <code>/orders/{uid}</code> – Auftrag lesen und ändern | ||
** | ** <code>/orders/{uid}/material</code> – Material erfassen | ||
* '''Berechtigung:''' Zugang ''Mobile-App'' für | ** <code>/abmelden</code> – Abmelden mit Zusatzaufgabe (siehe [[#Abmelden mit Zusatzaufgabe|Abmelden mit Zusatzaufgabe]]) | ||
* '''Berechtigung:''' Zugang ''Mobile-App'' für alle drei Endpunkte freigeschaltet | |||
Anmelden, Erneuern und Abmelden laufen über den JWT-Endpunkt <code>/auth</code>. Er braucht keinen Eintrag unter den Endpunkten und keine Berechtigung. | |||
== | == Anmeldeskript des Zugangs == | ||
Das Anmeldeskript ({{F7}} in der Zugänge-Liste) schreibt Mandant und Rollen als eigene Claims und fordert über <code>_OBS_JWT_REFRESH_ID</code> ein Refresh-Token an. Beim Erneuern ruft der Server im selben Skript die Methode <code>Refresh</code> auf. Einmalgebrauch, Rotation und Sperre der Refresh-Token führt der Server selbst; eine eigene Sperrtabelle ist nicht nötig. Alle Felder und Regeln: [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]. | |||
<syntaxhighlight lang="delphi"> | |||
// Schreibt die Token-Felder eines Technikers | |||
procedure _TokenFelder(oWriter: TxRestWriter; const cUser: string); | |||
begin | |||
oWriter.Int('status' , 1); | |||
oWriter.Str('_OBS_JWT_ID' , cUser); | |||
oWriter.Str('_OBS_JWT_SUBJECT' , cUser); | |||
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser)); | |||
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead" | |||
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // fordert ein Refresh-Token an | |||
end; | |||
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cUser: string; | |||
var | cPass: string; | ||
begin | begin | ||
cUser := ''; | |||
cPass := ''; | |||
oReader.Str('username', cUser); | |||
oReader.Str('password', cPass); | |||
if (PasswortPasst(cUser, cPass)) then begin | |||
_TokenFelder(oWriter, cUser); | |||
end else begin | |||
// Der Text geht als message an den Client (401 AUTH_FAILED) | |||
oWriter.Int('status', 9); | |||
oWriter.Str('error' , 'Login fehlgeschlagen'); | |||
end; | end; | ||
end; | end; | ||
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cUser: string; | |||
var | |||
begin | begin | ||
cUser := oReader.Subject(); | |||
// Der Text geht nur ins Protokoll. Der Client erhält 401 AUTH_EXPIRED | |||
// mit einer allgemeinen Meldung und muss sich neu anmelden. | |||
if (not TechnikerAktiv(cUser)) then begin | |||
oWriter.Int('status', 9); | |||
oWriter.Str('error' , 'Konto ist nicht mehr aktiv'); | |||
exit; | |||
end; | |||
// Mandant und Rollen neu lesen, damit ein Rechteentzug mit der | |||
// nächsten Erneuerung wirkt | |||
_TokenFelder(oWriter, cUser); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== | == Auftrag ändern mit ETag und If-Match == | ||
Das Skript des Endpunkts <code>/orders/{uid}</code> enthält <code>Get</code> und <code>Put</code>. <code>Get</code> liefert den Auftrag samt <code>ETag</code> (Versionszähler). <code>Put</code> prüft die Rolle aus dem Token und den Header <code>If-Match</code>. Clients senden den ETag-Wert in Anführungszeichen zurück, wie sie ihn erhalten haben; das Skript setzt ihn deshalb in Anführungszeichen und nimmt zusätzlich die Zahl ohne Anführungszeichen an. | |||
<syntaxhighlight lang="delphi"> | |||
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter); | |||
<syntaxhighlight lang=" | var cUid: string; | ||
nVer: Integer; | |||
var | |||
nVer: | |||
begin | begin | ||
cUid := oReader.Path('uid'); | |||
// AuftragLesen schreibt die Felder des Auftrags in die Wurzel und liefert die Version | |||
if (not AuftragLesen(oWriter, oReader.Claim('tenant'), cUid, nVer)) then begin | |||
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden'); | |||
exit; | |||
end; | end; | ||
oWriter.Header('ETag', '"' + IntToStr(nVer) + '"'); | |||
end; | end; | ||
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cUid : string; | |||
cIfMatch: string; | |||
var | nAktuell: Integer; | ||
nAktuell | |||
begin | begin | ||
// Nur die Rolle "lead" darf ändern. Die Rolle kommt aus dem Token, nicht | |||
// aus dem Körper. Mit Trennzeichen suchen, damit "teamlead" nicht trifft. | |||
if (Pos(',lead,', ',' + oReader.Claim('roles') + ',') = 0) then begin | |||
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Diese Rolle darf nicht ändern'); | |||
exit; | |||
end; | |||
cUid := oReader.Path('uid'); | |||
nAktuell := AuftragVersion(cUid); | |||
cIfMatch := AllTrim(oReader.Param('If-Match')); | |||
if ((cIfMatch <> '"' + IntToStr(nAktuell) + '"') and (cIfMatch <> IntToStr(nAktuell))) then begin | |||
// Der gültige ETag gehört auch an die Ablehnung, damit der Client | |||
// ohne weiteren Abruf neu ansetzen kann | |||
oWriter.Header('ETag', '"' + IntToStr(nAktuell) + '"'); | |||
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Auftrag wurde zwischenzeitlich geändert'); | |||
exit; | |||
end; | |||
// AuftragSpeichern liefert den Rückgabewert von SaveData und setzt die | |||
// Version auf nAktuell + 1 | |||
if (not AuftragSpeichern(cUid, oReader)) then begin | |||
oWriter.Error(500, 'INTERNAL_ERROR', 'Der Auftrag konnte nicht gespeichert werden'); | |||
exit; | |||
end; | |||
oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"'); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<code>VERSION_CONFLICT</code> ist ein eigener Code dieses Skripts. Der Server selbst verwendet für 409 den Code <code>CONFLICT</code>. | |||
== Material erfassen == | |||
Das Skript des Endpunkts <code>/orders/{uid}/material</code> erfasst mehrere Materialpositionen in einem Aufruf. Es prüft zuerst alle Positionen und schreibt erst danach. Ein Eingabefehler ergibt so eine vollständige 422-Antwort, ohne dass ein Schreibversuch stattfindet. Erfolgreiches Anlegen beantwortet es mit 201 und den vergebenen Positionen. | |||
Gegen doppelte Sendungen | Gegen doppelte Sendungen sendet der Client den Header <code>Idempotency-Key</code>. Das Skript muss dafür nichts tun: Der Server speichert die erfolgreiche Antwort und liefert sie bei einer Wiederholung erneut aus, ohne das Skript zu starten. Schlägt ein Schreibvorgang fehl und antwortet das Skript mit 500, nimmt der Server alle schon gebuchten Positionen dieses Aufrufs zurück. Regeln: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | ||
Skript muss dafür nichts tun | |||
[[OBS/Kostenpflichtige Module/ | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
// Körper: {"positionen":[{"artikel":"4711","menge":2}, | |||
// {"artikel":"0815","menge":1}]} | |||
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var cUid : string; | |||
nMenge: | cPos : string; | ||
cArtikel: string; | |||
cNeueUid: string; | |||
nMenge : Integer; | |||
nPreis : Double; | |||
nGesamt : Double; | |||
nAnz : Integer; | |||
nI : Integer; | |||
begin | begin | ||
cUid := oReader.Path('uid'); | |||
// 1) Gestalt prüfen. Count liefert 0, wenn das Feld fehlt oder keine | |||
// Liste ist; IsArr unterscheidet die beiden Fälle. | |||
// | if (not oReader.IsArr('positionen')) then begin | ||
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen muss eine Liste sein'); | |||
exit; | |||
end; | |||
nAnz := oReader.Count('positionen'); | |||
if (nAnz = 0) then begin | |||
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen ist leer'); | |||
exit; | |||
end; | |||
// 2) Alle Positionen prüfen, bevor die erste gebucht wird. | |||
// Punkt für Felder, eckige Klammern für Listeneinträge. | |||
for nI := 0 to nAnz - 1 do begin | |||
cPos := 'positionen[' + IntToStr(nI) + ']'; | |||
cArtikel := ''; | cArtikel := ''; | ||
nMenge := 0; | nMenge := 0; | ||
oReader.Str(cPos + '.artikel', cArtikel); | |||
oReader.Int(cPos + '.menge' , nMenge); | |||
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin | if ((Empty(cArtikel)) or (nMenge <= 0)) then begin | ||
oWriter.Error(422, 'VALIDATION_FAILED', | |||
'Position ' + IntToStr(nI + 1) + ': artikel und menge sind Pflicht'); | |||
exit; | exit; | ||
end; | end; | ||
end; | |||
// 3) Buchen und die Antwort in einem Durchgang schreiben | |||
nGesamt := 0; | |||
oWriter.ArrBegin('positionen'); | |||
for nI := 0 to nAnz - 1 do begin | |||
cPos := 'positionen[' + IntToStr(nI) + ']'; | |||
cArtikel := ''; | |||
nMenge := 0; | |||
oReader.Str(cPos + '.artikel', cArtikel); | |||
oReader.Int(cPos + '.menge' , nMenge); | |||
cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge); | cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge); | ||
if (Empty(cNeueUid)) then begin | if (Empty(cNeueUid)) then begin | ||
// Die offene Liste zuerst schließen, dann den Fehler setzen | |||
oWriter.ArrEnd; | |||
oWriter.Error(500, 'INTERNAL_ERROR', | |||
'Position ' + IntToStr(nI + 1) + ' konnte nicht gebucht werden'); | |||
exit; | exit; | ||
end; | end; | ||
nPreis := ArtikelPreis(cArtikel) * nMenge; | |||
nGesamt := nGesamt + nPreis; | |||
oWriter.ObjBegin(''); // leerer Name = Listeneintrag | |||
oWriter.Str('uid' , cNeueUid); | |||
oWriter.Str('artikel', cArtikel); | |||
oWriter.Int('menge' , nMenge); | |||
oWriter.Num('preis' , nPreis, 2); // zwei Nachkommastellen, Dezimalpunkt | |||
oWriter.ObjEnd; | |||
end; | end; | ||
oWriter.ArrEnd; | |||
oWriter.Num('gesamt', nGesamt, 2); | |||
oWriter.Status(201); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==Abmelden | == Abmelden mit Zusatzaufgabe == | ||
Für das reine Abmelden ist nichts einzurichten: Ein <code>DELETE</code> mit dem Access-Token an den JWT-Endpunkt <code>/auth</code> sperrt die Sitzung, siehe [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]. | |||
Soll beim Abmelden zusätzlich die Geräteregistrierung für Push-Nachrichten gelöscht werden, übernimmt das ein eigener Endpunkt <code>/abmelden</code>. Er erledigt seine Fachlogik und sperrt die Sitzung mit <code>oWriter.JwtRevoke</code>: | |||
Geräteregistrierung für Push | |||
erledigt seine Fachlogik und | |||
<syntaxhighlight lang=" | <syntaxhighlight lang="delphi"> | ||
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter); | |||
var | var cUmfang: string; | ||
lAlle : Boolean; | |||
begin | begin | ||
PushRegistrierungLoeschen(oReader.Subject()); | |||
// {"alleGeraete": true} meldet den Techniker auf allen Geräten ab | |||
lAlle := false; | |||
oReader.Bool('alleGeraete', lAlle); | |||
cUmfang := IIF(lAlle, 'all', 'session'); | |||
oWriter.JwtRevoke(cUmfang); | |||
oWriter.Status(204); | |||
oWriter.NoBody(); | |||
end; | end; | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Lässt sich die Sitzung nicht sperren, ersetzt der Server die Antwort durch 503 mit <code>Retry-After</code>. Die App wiederholt den Aufruf dann mit demselben <code>Idempotency-Key</code>. | |||
== Test mit curl == | |||
Anmelden (der JWT-Endpunkt braucht keinen <code>Idempotency-Key</code>): | |||
<syntaxhighlight lang="bash"> | |||
curl -X POST \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"username":"tech1","password":"geheim"}' \ | |||
https://obs.example.com/auth | |||
</syntaxhighlight> | |||
<syntaxhighlight lang="json"> | |||
"expiresIn":3600,"serverTime":"2026- | { | ||
"token": "eyJhbGciOiJIUzI1NiIs...", | |||
"accessToken": "eyJhbGciOiJIUzI1NiIs...", | |||
"refreshToken": "eyJhbGciOiJIUzI1NiIs...", | |||
"expiresIn": 3600, | |||
"serverTime": "2026-11-17T09:12:33+01:00" | |||
} | |||
</syntaxhighlight> | |||
Auftrag lesen; die Antwort trägt den Header <code>ETag: "7"</code>: | |||
<syntaxhighlight lang="bash"> | |||
curl -i \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Authorization: Bearer <accessToken>" \ | |||
https://obs.example.com/orders/4711 | |||
</syntaxhighlight> | |||
Ändern mit passendem <code>If-Match</code> ergibt 200, mit veraltetem 409: | |||
<syntaxhighlight lang="bash"> | |||
curl -i -X PUT \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Authorization: Bearer <accessToken>" \ | |||
-H "Idempotency-Key: 2d7f9b14-8c6e-4a31-b0f5-e94a3c6d1b72" \ | |||
-H 'If-Match: "7"' \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"status":"erledigt"}' \ | |||
https://obs.example.com/orders/4711 | |||
</syntaxhighlight> | |||
Material erfassen. Ein zweiter Aufruf mit demselben Schlüssel und demselben Körper liefert die gespeicherte Antwort mit dem Header <code>Idempotent-Replay: true</code>; es wird nichts erneut gebucht: | |||
<syntaxhighlight lang="bash"> | |||
curl -i -X POST \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Authorization: Bearer <accessToken>" \ | |||
-H "Idempotency-Key: 9c847f2a-3e1b-4c5d-8a6f-0b2e7d9c4a13" \ | |||
-H "Content-Type: application/json" \ | |||
-d '{"positionen":[{"artikel":"A100","menge":3},{"artikel":"B200","menge":1}]}' \ | |||
https://obs.example.com/orders/4711/material | |||
</syntaxhighlight> | |||
Token erneuern mit dem Refresh-Token am JWT-Endpunkt: | |||
<syntaxhighlight lang="bash"> | |||
curl -X POST \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Authorization: Bearer <refreshToken>" \ | |||
https://obs.example.com/auth | |||
</syntaxhighlight> | |||
Abmelden mit dem Access-Token am JWT-Endpunkt; der Server antwortet mit 204: | |||
<syntaxhighlight lang="bash"> | |||
curl -i -X DELETE \ | |||
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \ | |||
-H "Authorization: Bearer <accessToken>" \ | |||
https://obs.example.com/auth | |||
</syntaxhighlight> | |||
Wird dasselbe Access-Token danach noch verwendet, antwortet der Server mit 401: | |||
<syntaxhighlight lang="json"> | |||
{ | { | ||
"error": { | "error": { | ||
"code": | "code": "AUTH_EXPIRED", | ||
"uid": | "uid": "Y00G9TOK09", | ||
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden", | "message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden", | ||
"traceId": " | "traceId": "20261117T091233123-00001A" | ||
} | } | ||
} | } | ||
</ | </syntaxhighlight> | ||
Einmalgebrauch der Refresh-Token, gleichzeitiges Erneuern und alle Fehlerfälle beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]]. | |||
== Was zeigt das Beispiel? == | |||
* Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422, 500. | * Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422, 500. | ||
* Jeder Schreibzugriff wird auf Erfolg geprüft | * '''Liste aus dem Körper lesen''' über <code>oReader.IsArr</code>, <code>oReader.Count</code> und Pfade wie <code>positionen[0].artikel</code>. | ||
* | * '''Liste von Objekten schreiben''' mit <code>ArrBegin</code>, <code>ObjBegin('')</code> und <code>ArrEnd</code>, Kommazahlen über <code>oWriter.Num(name, wert, 2)</code>. | ||
* | * '''Erst prüfen, dann schreiben:''' ein Eingabefehler ergibt eine vollständige 422-Antwort ohne Schreibversuch. | ||
* Rollenprüfung aus dem Token | * '''Transaktion:''' scheitert eine Buchung, nimmt der Server alle Änderungen des Aufrufs zurück. | ||
* JWT mit | * Jeder Schreibzugriff wird auf Erfolg geprüft; ein gescheitertes <code>SaveData</code> kommt nicht als 200 oder 201 beim Client an. | ||
* | * Gleichzeitige Änderungen erkennen über <code>ETag</code> und <code>If-Match</code>, mit eigenem Code <code>VERSION_CONFLICT</code>. | ||
* Doppelte Sendungen abfangen über den <code>Idempotency-Key</code>, ohne Code im Skript. | |||
* | * Rollenprüfung aus dem Token über <code>oReader.Claim('roles')</code>, nicht aus dem Körper. | ||
* JWT mit eigenen Claims und Refresh-Token; Rotation und Sperre führt der Server. | |||
* <code>oWriter.JwtRevoke</code> für ein Abmelden mit Zusatzaufgabe oder auf allen Geräten. | |||
* <code>traceId</code> im Fehlerobjekt und im Header <code>X-Trace-Id</code> für die Fehlersuche. | |||
== Siehe auch == | |||
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Daten-Abruf mit JWT-Anmeldung|Beispiel 1: Daten-Abruf mit JWT-Authentifizierung]] | |||
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datei-Upload und Ablage|Beispiel 6: Datei-Upload und Ablage]] | |||
Aktuelle Version vom 17. November 2026, 07:23 Uhr
Schreibzugriff mit Statuscodes, ETag und Idempotenz
Dieses Beispiel zeigt schreibende Endpunkte für eine mobile App, wie sie im Außendienst täglich im Einsatz sind: Aufträge werden mit echten HTTP-Statuscodes geändert, gleichzeitige Änderungen über ETag und If-Match erkannt und doppelte Sendungen über den Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit eigenen Claims für Mandant und Rollen und mit Refresh-Token.
Die Hilfsfunktionen im Code (PasswortPasst, TechnikerMandant, TechnikerRollen, TechnikerAktiv, AuftragLesen, AuftragVersion, AuftragSpeichern, MaterialAnlegen, ArtikelPreis, PushRegistrierungLoeschen) stehen für Ihre Fachlogik. Sie sind kein Teil des REST-Servers.
Einrichtung in OBS
- Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
- Zugang: Mobile-App
- API-Key: vom System erzeugt
- Haken JWT-Authentifizierung gesetzt, Endpunkt
/auth, Secret-Key zufällig, Lebenszeit (Min) 60
- Endpunkte, alle mit Server Public-API:
/orders/{uid}– Auftrag lesen und ändern/orders/{uid}/material– Material erfassen/abmelden– Abmelden mit Zusatzaufgabe (siehe Abmelden mit Zusatzaufgabe)
- Berechtigung: Zugang Mobile-App für alle drei Endpunkte freigeschaltet
Anmelden, Erneuern und Abmelden laufen über den JWT-Endpunkt /auth. Er braucht keinen Eintrag unter den Endpunkten und keine Berechtigung.
Anmeldeskript des Zugangs
Das Anmeldeskript (F7 in der Zugänge-Liste) schreibt Mandant und Rollen als eigene Claims und fordert über _OBS_JWT_REFRESH_ID ein Refresh-Token an. Beim Erneuern ruft der Server im selben Skript die Methode Refresh auf. Einmalgebrauch, Rotation und Sperre der Refresh-Token führt der Server selbst; eine eigene Sperrtabelle ist nicht nötig. Alle Felder und Regeln: Anmeldung mit JWT.
// Schreibt die Token-Felder eines Technikers
procedure _TokenFelder(oWriter: TxRestWriter; const cUser: string);
begin
oWriter.Int('status' , 1);
oWriter.Str('_OBS_JWT_ID' , cUser);
oWriter.Str('_OBS_JWT_SUBJECT' , cUser);
oWriter.Str('_OBS_JWT_CLAIM_tenant', TechnikerMandant(cUser));
oWriter.Str('_OBS_JWT_CLAIM_roles' , TechnikerRollen(cUser)); // z.B. "tech,lead"
oWriter.Str('_OBS_JWT_REFRESH_ID' , GlobalUID()); // fordert ein Refresh-Token an
end;
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
cPass: string;
begin
cUser := '';
cPass := '';
oReader.Str('username', cUser);
oReader.Str('password', cPass);
if (PasswortPasst(cUser, cPass)) then begin
_TokenFelder(oWriter, cUser);
end else begin
// Der Text geht als message an den Client (401 AUTH_FAILED)
oWriter.Int('status', 9);
oWriter.Str('error' , 'Login fehlgeschlagen');
end;
end;
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
begin
cUser := oReader.Subject();
// Der Text geht nur ins Protokoll. Der Client erhält 401 AUTH_EXPIRED
// mit einer allgemeinen Meldung und muss sich neu anmelden.
if (not TechnikerAktiv(cUser)) then begin
oWriter.Int('status', 9);
oWriter.Str('error' , 'Konto ist nicht mehr aktiv');
exit;
end;
// Mandant und Rollen neu lesen, damit ein Rechteentzug mit der
// nächsten Erneuerung wirkt
_TokenFelder(oWriter, cUser);
end;
Auftrag ändern mit ETag und If-Match
Das Skript des Endpunkts /orders/{uid} enthält Get und Put. Get liefert den Auftrag samt ETag (Versionszähler). Put prüft die Rolle aus dem Token und den Header If-Match. Clients senden den ETag-Wert in Anführungszeichen zurück, wie sie ihn erhalten haben; das Skript setzt ihn deshalb in Anführungszeichen und nimmt zusätzlich die Zahl ohne Anführungszeichen an.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
nVer: Integer;
begin
cUid := oReader.Path('uid');
// AuftragLesen schreibt die Felder des Auftrags in die Wurzel und liefert die Version
if (not AuftragLesen(oWriter, oReader.Claim('tenant'), cUid, nVer)) then begin
oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
exit;
end;
oWriter.Header('ETag', '"' + IntToStr(nVer) + '"');
end;
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cIfMatch: string;
nAktuell: Integer;
begin
// Nur die Rolle "lead" darf ändern. Die Rolle kommt aus dem Token, nicht
// aus dem Körper. Mit Trennzeichen suchen, damit "teamlead" nicht trifft.
if (Pos(',lead,', ',' + oReader.Claim('roles') + ',') = 0) then begin
oWriter.Error(403, 'FORBIDDEN_ROLE', 'Diese Rolle darf nicht ändern');
exit;
end;
cUid := oReader.Path('uid');
nAktuell := AuftragVersion(cUid);
cIfMatch := AllTrim(oReader.Param('If-Match'));
if ((cIfMatch <> '"' + IntToStr(nAktuell) + '"') and (cIfMatch <> IntToStr(nAktuell))) then begin
// Der gültige ETag gehört auch an die Ablehnung, damit der Client
// ohne weiteren Abruf neu ansetzen kann
oWriter.Header('ETag', '"' + IntToStr(nAktuell) + '"');
oWriter.Error(409, 'VERSION_CONFLICT', 'Der Auftrag wurde zwischenzeitlich geändert');
exit;
end;
// AuftragSpeichern liefert den Rückgabewert von SaveData und setzt die
// Version auf nAktuell + 1
if (not AuftragSpeichern(cUid, oReader)) then begin
oWriter.Error(500, 'INTERNAL_ERROR', 'Der Auftrag konnte nicht gespeichert werden');
exit;
end;
oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
end;
VERSION_CONFLICT ist ein eigener Code dieses Skripts. Der Server selbst verwendet für 409 den Code CONFLICT.
Material erfassen
Das Skript des Endpunkts /orders/{uid}/material erfasst mehrere Materialpositionen in einem Aufruf. Es prüft zuerst alle Positionen und schreibt erst danach. Ein Eingabefehler ergibt so eine vollständige 422-Antwort, ohne dass ein Schreibversuch stattfindet. Erfolgreiches Anlegen beantwortet es mit 201 und den vergebenen Positionen.
Gegen doppelte Sendungen sendet der Client den Header Idempotency-Key. Das Skript muss dafür nichts tun: Der Server speichert die erfolgreiche Antwort und liefert sie bei einer Wiederholung erneut aus, ohne das Skript zu starten. Schlägt ein Schreibvorgang fehl und antwortet das Skript mit 500, nimmt der Server alle schon gebuchten Positionen dieses Aufrufs zurück. Regeln: HTTP-Schnittstelle.
// Körper: {"positionen":[{"artikel":"4711","menge":2},
// {"artikel":"0815","menge":1}]}
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid : string;
cPos : string;
cArtikel: string;
cNeueUid: string;
nMenge : Integer;
nPreis : Double;
nGesamt : Double;
nAnz : Integer;
nI : Integer;
begin
cUid := oReader.Path('uid');
// 1) Gestalt prüfen. Count liefert 0, wenn das Feld fehlt oder keine
// Liste ist; IsArr unterscheidet die beiden Fälle.
if (not oReader.IsArr('positionen')) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen muss eine Liste sein');
exit;
end;
nAnz := oReader.Count('positionen');
if (nAnz = 0) then begin
oWriter.Error(422, 'VALIDATION_FAILED', 'positionen ist leer');
exit;
end;
// 2) Alle Positionen prüfen, bevor die erste gebucht wird.
// Punkt für Felder, eckige Klammern für Listeneinträge.
for nI := 0 to nAnz - 1 do begin
cPos := 'positionen[' + IntToStr(nI) + ']';
cArtikel := '';
nMenge := 0;
oReader.Str(cPos + '.artikel', cArtikel);
oReader.Int(cPos + '.menge' , nMenge);
if ((Empty(cArtikel)) or (nMenge <= 0)) then begin
oWriter.Error(422, 'VALIDATION_FAILED',
'Position ' + IntToStr(nI + 1) + ': artikel und menge sind Pflicht');
exit;
end;
end;
// 3) Buchen und die Antwort in einem Durchgang schreiben
nGesamt := 0;
oWriter.ArrBegin('positionen');
for nI := 0 to nAnz - 1 do begin
cPos := 'positionen[' + IntToStr(nI) + ']';
cArtikel := '';
nMenge := 0;
oReader.Str(cPos + '.artikel', cArtikel);
oReader.Int(cPos + '.menge' , nMenge);
cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);
if (Empty(cNeueUid)) then begin
// Die offene Liste zuerst schließen, dann den Fehler setzen
oWriter.ArrEnd;
oWriter.Error(500, 'INTERNAL_ERROR',
'Position ' + IntToStr(nI + 1) + ' konnte nicht gebucht werden');
exit;
end;
nPreis := ArtikelPreis(cArtikel) * nMenge;
nGesamt := nGesamt + nPreis;
oWriter.ObjBegin(''); // leerer Name = Listeneintrag
oWriter.Str('uid' , cNeueUid);
oWriter.Str('artikel', cArtikel);
oWriter.Int('menge' , nMenge);
oWriter.Num('preis' , nPreis, 2); // zwei Nachkommastellen, Dezimalpunkt
oWriter.ObjEnd;
end;
oWriter.ArrEnd;
oWriter.Num('gesamt', nGesamt, 2);
oWriter.Status(201);
end;
Abmelden mit Zusatzaufgabe
Für das reine Abmelden ist nichts einzurichten: Ein DELETE mit dem Access-Token an den JWT-Endpunkt /auth sperrt die Sitzung, siehe Anmeldung mit JWT.
Soll beim Abmelden zusätzlich die Geräteregistrierung für Push-Nachrichten gelöscht werden, übernimmt das ein eigener Endpunkt /abmelden. Er erledigt seine Fachlogik und sperrt die Sitzung mit oWriter.JwtRevoke:
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cUmfang: string;
lAlle : Boolean;
begin
PushRegistrierungLoeschen(oReader.Subject());
// {"alleGeraete": true} meldet den Techniker auf allen Geräten ab
lAlle := false;
oReader.Bool('alleGeraete', lAlle);
cUmfang := IIF(lAlle, 'all', 'session');
oWriter.JwtRevoke(cUmfang);
oWriter.Status(204);
oWriter.NoBody();
end;
Lässt sich die Sitzung nicht sperren, ersetzt der Server die Antwort durch 503 mit Retry-After. Die App wiederholt den Aufruf dann mit demselben Idempotency-Key.
Test mit curl
Anmelden (der JWT-Endpunkt braucht keinen Idempotency-Key):
curl -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Content-Type: application/json" \
-d '{"username":"tech1","password":"geheim"}' \
https://obs.example.com/auth
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"expiresIn": 3600,
"serverTime": "2026-11-17T09:12:33+01:00"
}
Auftrag lesen; die Antwort trägt den Header ETag: "7":
curl -i \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
https://obs.example.com/orders/4711
Ändern mit passendem If-Match ergibt 200, mit veraltetem 409:
curl -i -X PUT \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
-H "Idempotency-Key: 2d7f9b14-8c6e-4a31-b0f5-e94a3c6d1b72" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d '{"status":"erledigt"}' \
https://obs.example.com/orders/4711
Material erfassen. Ein zweiter Aufruf mit demselben Schlüssel und demselben Körper liefert die gespeicherte Antwort mit dem Header Idempotent-Replay: true; es wird nichts erneut gebucht:
curl -i -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
-H "Idempotency-Key: 9c847f2a-3e1b-4c5d-8a6f-0b2e7d9c4a13" \
-H "Content-Type: application/json" \
-d '{"positionen":[{"artikel":"A100","menge":3},{"artikel":"B200","menge":1}]}' \
https://obs.example.com/orders/4711/material
Token erneuern mit dem Refresh-Token am JWT-Endpunkt:
curl -X POST \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <refreshToken>" \
https://obs.example.com/auth
Abmelden mit dem Access-Token am JWT-Endpunkt; der Server antwortet mit 204:
curl -i -X DELETE \
-H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
-H "Authorization: Bearer <accessToken>" \
https://obs.example.com/auth
Wird dasselbe Access-Token danach noch verwendet, antwortet der Server mit 401:
{
"error": {
"code": "AUTH_EXPIRED",
"uid": "Y00G9TOK09",
"message": "Die Sitzung ist nicht mehr gültig, bitte neu anmelden",
"traceId": "20261117T091233123-00001A"
}
}
Einmalgebrauch der Refresh-Token, gleichzeitiges Erneuern und alle Fehlerfälle beschreibt Anmeldung mit JWT.
Was zeigt das Beispiel?
- Echte HTTP-Statuscodes aus dem Skript: 201, 403, 404, 409, 422, 500.
- Liste aus dem Körper lesen über
oReader.IsArr,oReader.Countund Pfade wiepositionen[0].artikel. - Liste von Objekten schreiben mit
ArrBegin,ObjBegin()undArrEnd, Kommazahlen überoWriter.Num(name, wert, 2). - Erst prüfen, dann schreiben: ein Eingabefehler ergibt eine vollständige 422-Antwort ohne Schreibversuch.
- Transaktion: scheitert eine Buchung, nimmt der Server alle Änderungen des Aufrufs zurück.
- Jeder Schreibzugriff wird auf Erfolg geprüft; ein gescheitertes
SaveDatakommt nicht als 200 oder 201 beim Client an. - Gleichzeitige Änderungen erkennen über
ETagundIf-Match, mit eigenem CodeVERSION_CONFLICT. - Doppelte Sendungen abfangen über den
Idempotency-Key, ohne Code im Skript. - Rollenprüfung aus dem Token über
oReader.Claim('roles'), nicht aus dem Körper. - JWT mit eigenen Claims und Refresh-Token; Rotation und Sperre führt der Server.
oWriter.JwtRevokefür ein Abmelden mit Zusatzaufgabe oder auf allen Geräten.traceIdim Fehlerobjekt und im HeaderX-Trace-Idfür die Fehlersuche.