Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Schreibzugriff mit Statuscodes, ETag und Idempotenz: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite]
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(2 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Vorlage:Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
= Schreibzugriff mit Statuscodes, ETag und Idempotenz =


=Beispiel 5: 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.


Dieses Beispiel zeigt einen schreibenden Endpunkt für eine mobile App: Aufträge werden mit echten HTTP-Statuscodes aktualisiert, konkurrierende Änderungen über ETag/If-Match abgesichert (Optimistic Concurrency) und doppelte Sendungen über einen Idempotency-Key abgefangen. Die Anmeldung nutzt JWT mit Custom-Claims (Mandant, Rollen) und einem 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:''' Standard-TLS-Profil ''Public-API'' (Port 443)
* '''Zugang:''' ''Mobile-App''
* '''Zugang:''' ''Mobile-App''
** API-Key: zufällig generiert
** '''API-Key:''' vom System erzeugt
** JWT aktiv, JWT-Endpunkt ''auth'', JWT-Key zufällig, JWT-Exp 60 (Minuten)
** Haken '''JWT-Authentifizierung''' gesetzt, '''Endpunkt''' <code>/auth</code>, '''Secret-Key''' zufällig, '''Lebenszeit (Min)''' ''60''
* '''Endpunkte''' (beide dem Profil ''Public-API'' zugeordnet):
* '''Endpunkte''', alle mit '''Server''' ''Public-API'':
** ''orders/{uid}'' - Auftrag lesen/Ändern
** <code>/orders/{uid}</code> – Auftrag lesen und ändern
** ''orders/{uid}/material'' - Material erfassen
** <code>/orders/{uid}/material</code> – Material erfassen
* '''Berechtigung:''' Zugang ''Mobile-App'' für beide Endpunkte freigeschaltet
** <code>/abmelden</code> – Abmelden mit Zusatzaufgabe (siehe [[#Abmelden mit Zusatzaufgabe|Abmelden mit Zusatzaufgabe]])
* '''Berechtigung:''' Zugang ''Mobile-App'' für alle drei Endpunkte freigeschaltet


{{Hinweis|Für das Abmelden gibt es '''keinen eigenen Endpunkt'''. Es läuft über
Anmelden, Erneuern und Abmelden laufen über den JWT-Endpunkt <code>/auth</code>. Er braucht keinen Eintrag unter den Endpunkten und keine Berechtigung.
ein ''DELETE'' auf den JWT-Endpunkt ''auth'' und braucht daher weder eine Zeile
in ''RESTSRV_ENDPOINTS'' noch eine Berechtigung.}}


==JWT-Authentifizierungs-Skript (Zugang)==
== 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]].


Stellt Mandant und Rollen als Custom-Claims aus und löst über ''_OBS_JWT_REFRESH_ID'' ein Refresh-Token aus. Bei einem Refresh ruft der Server im selben Skript die Methode ''Refresh'' auf. Die Hilfsfunktionen (''PasswortPasst'', ''TechnikerMandant'', ''TechnikerRollen'', ''TechnikerAktiv'', ''AuftragLesen'', ''AuftragVersion'', ''AuftragSpeichern'', ''MaterialAnlegen'', ''ArtikelPreis'', ''PushRegistrierungLoeschen'') sind illustrativ und projektabhängig - sie stehen für Ihre Fachlogik, nicht für eine Server-API.
<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;


{{Hinweis|Eine '''eigene Sperrtabelle für Refresh-jti ist nicht nötig'''.
Einmalgebrauch, Rotation und Widerruf führt der Server in ''RESTSRV_TOKEN'' -
das Skript entscheidet nur, '''ob''' und '''mit welchen Rechten''' die Sitzung
fortgesetzt wird.}}
<syntaxhighlight lang="pascal" line>
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Authenticate(oReader: TxRestReader; oWriter: TxRestWriter);
var cUser: string;
var cUser: string;
Zeile 40: Zeile 45:


     if (PasswortPasst(cUser, cPass)) then begin
     if (PasswortPasst(cUser, cPass)) then begin
         oWriter.Int('status'              , 1);
         _TokenFelder(oWriter, cUser);
        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());   // loest das Refresh-Token aus
        // _OBS_JWT_REFRESH_EXP weggelassen -> Default 90 Tage
     end else begin
     end else begin
        // Der Text geht als message an den Client (401 AUTH_FAILED)
         oWriter.Int('status', 9);
         oWriter.Int('status', 9);
         oWriter.Str('error' , 'Login fehlgeschlagen');
         oWriter.Str('error' , 'Login fehlgeschlagen');
     end;
     end;
end;
end;
//------------------------------------------------------------------------------


procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Refresh(oReader: TxRestReader; oWriter: TxRestWriter);
Zeile 60: Zeile 58:
     cUser := oReader.Subject();
     cUser := oReader.Subject();


     // Das vorgelegte Refresh-Token hat der Server bereits geprueft und
     // Der Text geht nur ins Protokoll. Der Client erhält 401 AUTH_EXPIRED
    // entwertet. Hier wird nur entschieden, ob die Sitzung fortgesetzt
     // mit einer allgemeinen Meldung und muss sich neu anmelden.
     // werden darf - und mit welchen Rechten.
     if (not TechnikerAktiv(cUser)) then begin
     if (not TechnikerAktiv(cUser)) then begin
         oWriter.Int('status', 9);
         oWriter.Int('status', 9);
         oWriter.Str('error' , 'Konto ist nicht mehr aktiv, bitte neu anmelden');
         oWriter.Str('error' , 'Konto ist nicht mehr aktiv');
         exit;
         exit;
     end;
     end;


     // Mandant und Rollen NEU lesen, nicht aus dem alten Token uebernehmen -
     // Mandant und Rollen neu lesen, damit ein Rechteentzug mit der
     // sonst wirkt ein Rechteentzug erst beim naechsten Login.
     // nächsten Erneuerung wirkt
    oWriter.Int('status'              , 1);
     _TokenFelder(oWriter, cUser);
    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));
    oWriter.Str('_OBS_JWT_REFRESH_ID'  , GlobalUID());
end;
end;
</syntaxhighlight>
</syntaxhighlight>


==Endpunkt ''orders/{uid}'' - ändern mit ETag / If-Match==
== 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.


''GET'' liefert den Auftrag samt ''ETag'' (Version), ''PUT'' prüft Rolle und ''If-Match''.
<syntaxhighlight lang="delphi">
 
<syntaxhighlight lang="pascal" line>
// AuftragLesen bekommt den WRITER und schreibt die Felder des Auftrags in die
// Wurzel; nVer kommt als var-Parameter zurueck. Vorher wurde ihm das
// Antwortobjekt hineingegeben - derselbe Gedanke, nur ohne Objekt.
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
var cUid: string;
Zeile 93: Zeile 81:
begin
begin
     cUid := oReader.Path('uid');
     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
     if (not AuftragLesen(oWriter, oReader.Claim('tenant'), cUid, nVer)) then begin
         oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
         oWriter.Error(404, 'NOT_FOUND', 'Auftrag nicht gefunden');
         exit;
         exit;
     end;
     end;
     oWriter.Header('ETag', xStr(nVer));
     oWriter.Header('ETag', '"' + IntToStr(nVer) + '"');
end;
end;
//------------------------------------------------------------------------------


procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid    : string;
var cUid    : string;
    cIfMatch: string;
     nAktuell: Integer;
     nAktuell: Integer;
    nIfMatch: Integer;
begin
begin
     // nur Rolle "lead" darf ändern - Rolle kommt aus dem Token, nicht aus dem Body.
     // Nur die Rolle "lead" darf ändern. Die Rolle kommt aus dem Token, nicht
     // Mit Trennzeichen suchen: ein blosses Pos('lead', ...) wuerde auch in
     // aus dem Körper. Mit Trennzeichen suchen, damit "teamlead" nicht trifft.
    // "leadless" oder "teamlead" treffen.
     if (Pos(',lead,', ',' + oReader.Claim('roles') + ',') = 0) then begin
     if (Pos(',lead,', ',' + oReader.Claim('roles') + ',') = 0) then begin
         oWriter.Error(403, 'FORBIDDEN_ROLE', 'Diese Rolle darf nicht aendern');
         oWriter.Error(403, 'FORBIDDEN_ROLE', 'Diese Rolle darf nicht ändern');
         exit;
         exit;
     end;
     end;
Zeile 117: Zeile 103:
     cUid    := oReader.Path('uid');
     cUid    := oReader.Path('uid');
     nAktuell := AuftragVersion(cUid);
     nAktuell := AuftragVersion(cUid);
     nIfMatch := iVal(oReader.Param('if-match'));
     cIfMatch := AllTrim(oReader.Param('If-Match'));


     if (nIfMatch <> nAktuell) then begin
     if ((cIfMatch <> '"' + IntToStr(nAktuell) + '"') and (cIfMatch <> IntToStr(nAktuell))) then begin
         // Der ETag gehoert AUCH an die Ablehnung - sonst kennt der Client den
         // Der gültige ETag gehört auch an die Ablehnung, damit der Client
         // gueltigen Wert nicht und sein naechster Versuch scheitert wieder.
         // ohne weiteren Abruf neu ansetzen kann
        // Header und Error stoeren sich nicht: Error ersetzt nur den Koerper.
         oWriter.Header('ETag', '"' + IntToStr(nAktuell) + '"');
         oWriter.Header('ETag', xStr(nAktuell));
         oWriter.Error(409, 'VERSION_CONFLICT', 'Der Auftrag wurde zwischenzeitlich geändert');
         oWriter.Error(409, 'VERSION_CONFLICT', 'Der Auftrag wurde zwischenzeitlich geaendert');
         exit;
         exit;
     end;
     end;


     // AuftragSpeichern gibt den Rueckgabewert von SaveData durch. Ohne
     // AuftragSpeichern liefert den Rückgabewert von SaveData und setzt die
    // diese Pruefung antwortet der Endpunkt mit 200 und einem neuen ETag,
     // Version auf nAktuell + 1
     // obwohl nichts geschrieben wurde - siehe Scripting, Schreibfehler
     if (not AuftragSpeichern(cUid, oReader)) then begin
    // erkennen.
     if (not AuftragSpeichern(cUid, oReader)) then begin   // setzt Version auf nAktuell + 1
         oWriter.Error(500, 'INTERNAL_ERROR', 'Der Auftrag konnte nicht gespeichert werden');
         oWriter.Error(500, 'INTERNAL_ERROR', 'Der Auftrag konnte nicht gespeichert werden');
         exit;
         exit;
     end;
     end;


     oWriter.Header('ETag', xStr(nAktuell + 1));
     oWriter.Header('ETag', '"' + IntToStr(nAktuell + 1) + '"');
end;
end;
</syntaxhighlight>
</syntaxhighlight>


==Endpunkt ''orders/{uid}/material'' - idempotentes Anlegen==
<code>VERSION_CONFLICT</code> ist ein eigener Code dieses Skripts. Der Server selbst verwendet für 409 den Code <code>CONFLICT</code>.


''POST'' erfasst '''mehrere''' Materialpositionen in einem Aufruf: Validierungsfehler -> 422, erfolgreiches Anlegen -> 201 mit den vergebenen Positionen.
== 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 schickt der Client den Header ''Idempotency-Key''. '''Das
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''' - der Server erkennt den Header, merkt sich das
Ergebnis und liefert bei einer Wiederholung mit demselben Schlüssel die
gespeicherte Antwort zurück, ohne das Skript erneut zu starten (siehe
[[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]], Abschnitt
Idempotenz). Das Skript kümmert sich nur um seine Fachlogik:


<syntaxhighlight lang="pascal" line>
<syntaxhighlight lang="delphi">
// Koerper: {"positionen":[{"artikel":"4711","menge":2},
// Körper: {"positionen":[{"artikel":"4711","menge":2},
//                         {"artikel":"0815","menge":1}]}
//                         {"artikel":"0815","menge":1}]}
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid     : string;
var cUid   : string;
     cPos     : string;
     cPos   : string;
     cArtikel : string;
     cArtikel: string;
     cNeueUid : string;
     cNeueUid: string;
     nMenge   : Integer;
     nMenge : Integer;
     nPreis   : Double;
     nPreis : Double;
     nGesamt : Double;
     nGesamt : Double;
     nAnz     : Integer;
     nAnz   : Integer;
     nI       : Integer;
     nI     : Integer;
begin
begin
     cUid := oReader.Path('uid');
     cUid := oReader.Path('uid');


     // 1) Gestalt pruefen. Count liefert 0, wenn das Feld fehlt ODER keine
     // 1) Gestalt prüfen. Count liefert 0, wenn das Feld fehlt oder keine
     //    Liste ist - IsArr unterscheidet die beiden Faelle. Ein Objekt, wo
     //    Liste ist; IsArr unterscheidet die beiden Fälle.
    //    eine Liste erwartet wird, ist etwas anderes als eine leere Liste.
    nAnz := oReader.Count('positionen');
     if (not oReader.IsArr('positionen')) then begin
     if (not oReader.IsArr('positionen')) then begin
         oWriter.Error(422, 'VALIDATION_FAILED', 'positionen muss eine Liste sein');
         oWriter.Error(422, 'VALIDATION_FAILED', 'positionen muss eine Liste sein');
         exit;
         exit;
     end;
     end;
    nAnz := oReader.Count('positionen');
     if (nAnz = 0) then begin
     if (nAnz = 0) then begin
         oWriter.Error(422, 'VALIDATION_FAILED', 'positionen ist leer');
         oWriter.Error(422, 'VALIDATION_FAILED', 'positionen ist leer');
Zeile 181: Zeile 159:
     end;
     end;


     // 2) ALLE Positionen pruefen, BEVOR die erste gebucht wird. Sonst
     // 2) Alle Positionen prüfen, bevor die erste gebucht wird.
     //    haette ein Fehler in Position 3 zwei gebuchte Zeilen und eine
     //    Punkt für Felder, eckige Klammern für Listeneinträge.
    //    Fehlerantwort hinterlassen - der Client wiederholt und bucht die
    //    ersten zwei erneut.
    //
    //    Verschachtelung steht im Pfad: Punkt fuer Felder, eckige Klammern
    //    fuer Listeneintraege.
     for nI := 0 to nAnz - 1 do begin
     for nI := 0 to nAnz - 1 do begin
         cPos    := 'positionen[' + IntToStr(nI) + ']';
         cPos    := 'positionen[' + IntToStr(nI) + ']';
Zeile 201: Zeile 174:
     end;
     end;


     // 3) Buchen und antworten in EINEM Durchgang. Die Positionsnummern
     // 3) Buchen und die Antwort in einem Durchgang schreiben
    //    entstehen beim Buchen, also schreibt die Schleife sie an der Stelle,
    //    an die sie gehoeren - gesammelt und am Ende eingesetzt werden muss
    //    nichts.
     nGesamt := 0;
     nGesamt := 0;
     oWriter.ArrBegin('positionen');
     oWriter.ArrBegin('positionen');
Zeile 216: Zeile 186:
         cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);
         cNeueUid := MaterialAnlegen(cUid, cArtikel, nMenge);
         if (Empty(cNeueUid)) then begin
         if (Empty(cNeueUid)) then begin
             // Der Stapel wird GESCHLOSSEN, bevor der Fehler gesetzt wird:
             // Die offene Liste zuerst schließen, dann den Fehler setzen
            // oWriter.Error verwirft zwar den begonnenen Koerper, aber ein
            // offener ArrBegin bleibt ein Strukturfehler - dann antwortet der
            // Server 500 mit "Verschachtelung nicht geschlossen" statt mit
            // dieser Meldung.
             oWriter.ArrEnd;
             oWriter.ArrEnd;
             oWriter.Error(500, 'INTERNAL_ERROR',
             oWriter.Error(500, 'INTERNAL_ERROR',
Zeile 234: Zeile 200:
             oWriter.Str('artikel', cArtikel);
             oWriter.Str('artikel', cArtikel);
             oWriter.Int('menge'  , nMenge);
             oWriter.Int('menge'  , nMenge);
            // Zwei Nachkommastellen, immer mit Dezimalpunkt. Selbst
             oWriter.Num('preis'  , nPreis, 2);   // zwei Nachkommastellen, Dezimalpunkt
            // formatiert stand bei Werten ab 1000 der Tausendertrenner im
            // JSON - gueltiges JSON, falscher Wert, keine Meldung.
             oWriter.Num('preis'  , nPreis, 2);
         oWriter.ObjEnd;
         oWriter.ObjEnd;
     end;
     end;
Zeile 247: Zeile 210:
</syntaxhighlight>
</syntaxhighlight>


==Abmelden - ohne Endpunkt und ohne Skript==
== 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]].


Beim Abmelden soll das Gerät seine Sitzung wirklich verlieren, nicht erst mit dem
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>:
Ablauf des Tokens. Dafür ist '''nichts einzurichten''': ein ''DELETE'' auf den
JWT-Endpunkt mit dem Access-Token genügt, der Server sperrt die Sitzung in
''RESTSRV_TOKEN'' und antwortet 204.


Gesperrt wird die ganze Sitzung, also auch die Access-Token vorheriger
<syntaxhighlight lang="delphi">
Erneuerungen. Ein zweiter Aufruf ist unschädlich und bleibt 204. Kann der Server
die Sitzung nicht sperren, antwortet er '''503''' mit ''Retry-After'' - die App
wiederholt den Abmeldevorgang dann.
 
Nur wenn beim Abmelden zusätzlich etwas passieren soll - hier: die
Geräteregistrierung für Push löschen -, braucht es einen eigenen Endpunkt. Er
erledigt seine Fachlogik und ruft ''oWriter.JwtRevoke'':
 
<syntaxhighlight lang="pascal" line>
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var cAlle : string;
var cUmfang: string;
     lAlle : Boolean;
     lAlle : Boolean;
begin
begin
     PushRegistrierungLoeschen(oReader.Claim('technikerUid'));
     PushRegistrierungLoeschen(oReader.Subject());


     // Optional: {"alleGeraete": true} meldet den Techniker ueberall ab.
     // {"alleGeraete": true} meldet den Techniker auf allen Geräten ab
    // Diese Entscheidung gehoert bewusst in ein Skript - sie braucht eine
    // Berechtigungspruefung, die der JWT-Endpunkt nicht leisten kann.
     lAlle := false;
     lAlle := false;
     oReader.Bool('alleGeraete', lAlle);
     oReader.Bool('alleGeraete', lAlle);
     cAlle := IIF(lAlle, 'all', 'session');
     cUmfang := IIF(lAlle, 'all', 'session');


     oWriter.JwtRevoke(cAlle);
     oWriter.JwtRevoke(cUmfang);
     oWriter.Status(204);
     oWriter.Status(204);
     oWriter.NoBody();
     oWriter.NoBody();
Zeile 283: Zeile 233:
</syntaxhighlight>
</syntaxhighlight>


==Test mit curl==
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>.


Token holen:
== Test mit curl ==
Anmelden (der JWT-Endpunkt braucht keinen <code>Idempotency-Key</code>):


curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
<syntaxhighlight lang="bash">
      -d "{\"username\":\"tech1\",\"password\":\"geheim\"}" ^
curl -X POST \
      https://api.meinserver.de/auth/
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Content-Type: application/json" \
    -d '{"username":"tech1","password":"geheim"}' \
    https://obs.example.com/auth
</syntaxhighlight>


{"token":"eyJ...","accessToken":"eyJ...","refreshToken":"eyJ...",
<syntaxhighlight lang="json">
   "expiresIn":3600,"serverTime":"2026-06-29T15:30:12+02:00"}
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
   "expiresIn": 3600,
  "serverTime": "2026-11-17T09:12:33+01:00"
}
</syntaxhighlight>


Bei falschen Zugangsdaten antwortet der Server mit '''401''' und dem Text aus dem
Auftrag lesen; die Antwort trägt den Header <code>ETag: "7"</code>:
Authenticate-Skript als ''error.message''.


Auftrag lesen (liefert den ETag-Header):
<syntaxhighlight lang="bash">
curl -i \
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Authorization: Bearer <accessToken>" \
    https://obs.example.com/orders/4711
</syntaxhighlight>


curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
Ändern mit passendem <code>If-Match</code> ergibt 200, mit veraltetem 409:
      https://api.meinserver.de/orders/4711
... ETag: 7


ändern mit korrektem If-Match -> 200, mit veraltetem If-Match -> 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>


curl -i -X PUT -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
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:
      -H "If-Match: 7" -H "Content-Type: application/json" ^
      -d "{\"status\":\"erledigt\"}" ^
      https://api.meinserver.de/orders/4711


Material idempotent erfassen (zweiter Aufruf mit gleichem Key -> gleiche Antwort, keine Doppelbuchung):
<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>


curl -i -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
Token erneuern mit dem Refresh-Token am JWT-Endpunkt:
      -H "Idempotency-Key: 9c84-7f2a-..." -H "Content-Type: application/json" ^
      -d "{\"positionen\":[{\"artikel\":\"A100\",\"menge\":3},{\"artikel\":\"B200\",\"menge\":1}]}" ^
      https://api.meinserver.de/orders/4711/material


Die Antwort des zweiten Aufrufs trägt zusätzlich den Header
<syntaxhighlight lang="bash">
''Idempotent-Replay: true'' - daran ist erkennbar, dass sie aus dem Speicher kam
curl -X POST \
und nichts erneut gebucht wurde.
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Authorization: Bearer <refreshToken>" \
    https://obs.example.com/auth
</syntaxhighlight>


Token erneuern (Refresh-Token im Authorization-Header an denselben JWT-Endpunkt):
Abmelden mit dem Access-Token am JWT-Endpunkt; der Server antwortet mit 204:


curl -X POST -H "apikey: [API-KEY]" -H "Authorization: Bearer <refreshToken>" ^
<syntaxhighlight lang="bash">
      https://api.meinserver.de/auth/
curl -i -X DELETE \
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Authorization: Bearer <accessToken>" \
    https://obs.example.com/auth
</syntaxhighlight>


Die Antwort enthält ein neues Paar. Das alte Refresh-Token ist damit verbraucht:
Wird dasselbe Access-Token danach noch verwendet, antwortet der Server mit 401:
ein zweiter Aufruf mit demselben Token antwortet '''401'''. Erfolgt er innerhalb
von 60 Sekunden, bleibt die Sitzung bestehen (paralleler Refresh der App); später
gilt er als Wiedervorlage und die '''ganze Sitzung wird gesperrt''' - der
Techniker muss sich neu anmelden, und der Vorfall steht mit IP im Protokoll.


Abmelden - DELETE auf denselben JWT-Endpunkt, Access-Token im Header:
<syntaxhighlight lang="json">
 
curl -i -X DELETE -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
      https://api.meinserver.de/auth/
 
HTTP/1.1 204 No Content
 
Derselbe Token danach noch einmal verwendet:
 
curl -i -H "apikey: [API-KEY]" -H "Authorization: Bearer eyJ..." ^
      https://api.meinserver.de/orders/4711
 
HTTP/1.1 401 Unauthorized
 
<pre>
{
{
   "error": {
   "error": {
     "code":   "AUTH_EXPIRED",
     "code": "AUTH_EXPIRED",
     "uid":     "Y00G9TOK09",
     "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": "20260819T091233123-00001A"
     "traceId": "20261117T091233123-00001A"
   }
   }
}
}
</pre>
</syntaxhighlight>


==Was zeigt das Beispiel?==
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.
* Eine '''Liste aus dem Körper lesen''' über ''oReader.Count'' und Pfade wie ''positionen[0].artikel'' - ohne Cast, ohne ''.Items[i]''.
* '''Liste aus dem Körper lesen''' über <code>oReader.IsArr</code>, <code>oReader.Count</code> und Pfade wie <code>positionen[0].artikel</code>.
* Eine '''benannte Liste von Objekten schreiben''' (''ArrBegin'' / ''ObjBegin('')'' / ''ArrEnd'') und '''Kommazahlen''' über ''oWriter.Num(name, wert, 2)''.
* '''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''': Alle Positionen werden validiert, bevor die erste gebucht wird - sonst hinterlässt ein Fehler in Position 3 zwei gebuchte Zeilen und eine Fehlerantwort.
* '''Erst prüfen, dann schreiben:''' ein Eingabefehler ergibt eine vollständige 422-Antwort ohne Schreibversuch.
* '''Den Stapel schließen, bevor ein Fehler gesetzt wird''' - ein offener ''ArrBegin'' ist auch bei ''oWriter.Error'' ein Strukturfehler.
* '''Transaktion:''' scheitert eine Buchung, nimmt der Server alle Änderungen des Aufrufs zurück.
* Jeder Schreibzugriff wird auf Erfolg geprüft - ein gescheitertes ''SaveData'' darf nicht als 200 oder 201 beim Client ankommen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting#Schreibfehler erkennen|Schreibfehler erkennen]]).
* Jeder Schreibzugriff wird auf Erfolg geprüft; ein gescheitertes <code>SaveData</code> kommt nicht als 200 oder 201 beim Client an.
* Optimistic Concurrency über ''ETag'' (GET) und ''If-Match'' (PUT) -> 409 VERSION_CONFLICT.
* Gleichzeitige Änderungen erkennen über <code>ETag</code> und <code>If-Match</code>, mit eigenem Code <code>VERSION_CONFLICT</code>.
* Idempotente Schreibzugriffe über den ''Idempotency-Key'' - '''vom Server erledigt''', das Skript enthält dafür keine Zeile Code.
* Doppelte Sendungen abfangen über den <code>Idempotency-Key</code>, ohne Code im Skript.
* Rollenprüfung aus dem Token-Claim über ''oReader.Claim('roles')'', nicht aus dem Body.
* Rollenprüfung aus dem Token über <code>oReader.Claim('roles')</code>, nicht aus dem Körper.
* JWT mit Custom-Claims (''tenant''/''roles'') und Refresh-Token mit Rotation - '''vom Server erledigt''', das Skript führt keine Sperrtabelle.
* JWT mit eigenen Claims und Refresh-Token; Rotation und Sperre führt der Server.
* Anmelden, Erneuern und Abmelden über '''einen''' Endpunkt - Abmelden als ''DELETE'', ohne eigene Endpunkt-Zeile und ohne Skript.
* <code>oWriter.JwtRevoke</code> für ein Abmelden mit Zusatzaufgabe oder auf allen Geräten.
* ''oWriter.JwtRevoke'' für den Fall, dass beim Abmelden zusätzlich Fachlogik laufen soll oder alle Geräte gemeint sind.
* <code>traceId</code> im Fehlerobjekt und im Header <code>X-Trace-Id</code> für die Fehlersuche.
* ''traceId'' im Fehler-Body für die Support-Nachverfolgung (auch als Header ''X-Trace-Id'').
 
== 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.Count und Pfade wie positionen[0].artikel.
  • Liste von Objekten schreiben mit ArrBegin, ObjBegin() und ArrEnd, Kommazahlen über oWriter.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 SaveData kommt nicht als 200 oder 201 beim Client an.
  • Gleichzeitige Änderungen erkennen über ETag und If-Match, mit eigenem Code VERSION_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.JwtRevoke für ein Abmelden mit Zusatzaufgabe oder auf allen Geräten.
  • traceId im Fehlerobjekt und im Header X-Trace-Id für die Fehlersuche.

Siehe auch