Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Beispiele/Datensatz anlegen mit JSON-Körper: Unterschied zwischen den Versionen

Aus OBS Wiki
Böhrer (Diskussion | Beiträge)
Die Seite wurde neu angelegt: „Monster Legends is an island builder that permits the player to gather monsters and practice them for battles in the wild or against players. The characters a…“
 
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(13 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
Monster Legends is an island builder that permits the player to gather monsters and practice them for battles in the wild or against players. The characters are each sturdy and quite a few, but whereas there are countless forged members, unlike many shows where there are giant amounts of characters which are completely [https://www.Change.org/search?q=useless useless] and contribute nothing to the plot, every character in Monster brings one thing to the mix.<br><br>Rustic wood incorporates many natural traits including open and closed knots, pitch pockets, rasped edges, gouges, wormholes, small season checks, mineral streaks, dramatic shade [http://Www.europeana.eu/portal/search.html?query=distinction distinction] and different pure variations all reflecting the inherent beauty of the wooden.<br><br>It can be tempting to get caught up in the fun of breeding and elevating monsters, with out paying enough attention to the talents that you have unlocked for each of them (or the talents that you still have not unlocked!) Every monster has a different [http://get-gems.postbit.com/emotions-around-the-monster-legends-hack.html cheat in monster legends gems] assortment of abilities, and if you wish to reach battles-rather than just sitting around raising monsters all day-then you definately'll need to know what they're capable of!<br><br>To actually turn into the stuff of [http://mombao3.livejournal.com/620.html legends of tomorrow cast amaya], you will have to use the free BlueStacks Android Emulator to play Monster Legends on COMPUTER or Mac. The supporting solid is just as essential as a result of they are the means that help this anime arrive at a profitable end.<br><br>What separates Rings from other puzzle video games is it appears to do an excellent job of giving you a way out when the board is almost full. The level meter on the prime of the sport display screen exhibits how many XP you've collected and the remaining XP it is advisable to stage up.
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
= Datensatz anlegen mit JSON-Körper =
 
Dieses Beispiel zeigt einen Endpunkt mit allen vier Grundzugriffen: lesen (<code>GET</code>), anlegen (<code>POST</code>), ändern (<code>PUT</code>) und schließen (<code>DELETE</code>). Ein externer Servicedesk liefert damit Tickets in OBS ein, ruft sie ab, aktualisiert und schließt sie – direkt, ohne Dateiaustausch.
 
{{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über den Query-Parameter <code>?id=…</code>. Dieselbe Ressource lässt sich auch über ein Pfad-Template wie <code>/tickets/{id}</code> ansprechen; die ID steht dann in <code>oReader.Path('id')</code>. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4]].}}
 
== Einrichtung in OBS ==
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443
* '''Zugang:''' ''Servicedesk-X''
** '''API-Key:''' vom System erzeugt
** '''Host:''' ''servicedesk.example.com''. Der Server nimmt Anfragen dieses Zugangs nur von der Adresse an, auf die der Name auflöst; andere Absender erhalten 403.
** '''JWT-Authentifizierung:''' nicht gesetzt
* '''Endpunkt:''' '''Pfad-Template''' <code>/tickets/v1</code>, '''Server''' ''Public-API''
* '''Berechtigung:''' Zugang ''Servicedesk-X'' für den Endpunkt <code>/tickets/v1</code> freigeschaltet
 
== Endpunkt-Skript ==
Das Skript enthält je HTTP-Methode eine gleichnamige Prozedur. <code>POST</code>, <code>PUT</code> und <code>DELETE</code> laufen in einer Datenbanktransaktion: Endet das Skript mit einem Status ab 400 oder mit einem Laufzeitfehler, nimmt der Server alle Änderungen zurück. Details: [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]].
 
<syntaxhighlight lang="delphi">
// Schreibt die Felder eines Tickets in das Objekt, das der Aufrufer geöffnet hat
procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
                        const cOffset: string);
begin
    oWriter.Str ('id'    , qTicket.A2UID());
    oWriter.Str ('nr'    , qTicket.A2C('ti_nr'));
    oWriter.Str ('betreff', qTicket.A2C('ti_betreff'));
    oWriter.Str ('status' , qTicket.A2C('ti_status'));
    oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
    // Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
    oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;
 
//------------------------------------------------------------------------------
// GET /tickets/v1?id=...  einzelnes Ticket
// GET /tickets/v1          alle offenen Tickets
//------------------------------------------------------------------------------
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql    : string;
    qData    : TxFQuery;
    cId      : string;
    cOffset  : string;
    lGefunden: Boolean;
begin
    cId    := oReader.Param('id');
    cOffset := oReader.Offset();
 
    if (not Empty(cId)) then begin
        lGefunden := false;
        cSql := 'SELECT * FROM TICKETS WHERE sys_uid = ' + DB_SqlVal(cId, 'C');
        if (DB_SOpen(oDB, cSql, qData)) then begin
            if (not qData.EoF) then begin
                _TicketFelder(oWriter, qData, cOffset);
                lGefunden := true;
            end;
        end;
        DB_Close(qData);
 
        if (not lGefunden) then begin
            oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        end;
    end else begin
        // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
        oWriter.RootArr();
        cSql := 'SELECT * FROM TICKETS' +
                ' WHERE ti_status <> ' + DB_SqlVal('9', 'C') +
                ' ORDER BY ti_aend_dat DESC';
        if (DB_SOpen(oDB, cSql, qData)) then begin
            while (not qData.EoF) do begin
                oWriter.ObjBegin('');
                    _TicketFelder(oWriter, qData, cOffset);
                oWriter.ObjEnd;
                qData.Next();
            end;
        end;
        DB_Close(qData);
    end;
end;
 
//------------------------------------------------------------------------------
// POST /tickets/v1        neues Ticket anlegen
// Körper: {"betreff":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket : TqSQL;
    cId    : string;
    cBetreff: string;
    cBeschr : string;
    lOk    : Boolean;
begin
    // Kein Körper ist 400, ein fehlendes Feld 422
    if (not oReader.HasBody()) then begin
        oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
        exit;
    end;
 
    cBetreff := '';
    cBeschr  := '';
    oReader.Str('betreff', cBetreff);
    oReader.Str('beschr' , cBeschr);
 
    if (Empty(cBetreff)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
        exit;
    end;
 
    cId := GetNewId(oDB);
 
    lOk    := false;
    qTicket := qSqlInit(oDB, 'TICKETS');
    qTicket.lNoSysUID := true;
    try
        qTicket.qSet('sys_uid'    , cId);
        qTicket.qSet('ti_nr'      , DB_NeuNum(oDB, 'TICKETS', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
        qTicket.qSet('ti_betreff' , cBetreff);
        qTicket.qSet('ti_beschr'  , cBeschr);
        qTicket.qSet('ti_status'  , '1');
        qTicket.qSet('ti_anl_dat' , Now());
        qTicket.qSet('ti_aend_dat', Now());
        // Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
        lOk := qTicket.SaveData(NEW_RECORD);
    finally
        qSqlFree(qTicket);
    end;
 
    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
        exit;
    end;
 
    oWriter.Str('id'    , cId);
    oWriter.Str('status', 'created');
    oWriter.Status(201);
    oWriter.Header('Location', '/tickets/v1?id=' + cId);
end;
 
//------------------------------------------------------------------------------
// PUT /tickets/v1          Ticket aktualisieren
// Körper: {"id":"...", "status":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
    lOk    : Boolean;
    cId    : string;
    cStat  : string;
    cBeschr: string;
begin
    if (not oReader.HasBody()) then begin
        oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
        exit;
    end;
 
    cId    := '';
    cStat  := '';
    cBeschr := '';
    oReader.Str('id'    , cId);
    oReader.Str('status', cStat);
    oReader.Str('beschr', cBeschr);
 
    if (Empty(cId)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
        exit;
    end;
 
    if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        exit;
    end;
 
    // Ändern: qSqlInit mit sys_uid als Schreib-Index
    lOk    := false;
    qTicket := qSqlInit(oDB, 'TICKETS');
    try
        qTicket.qSet('sys_uid', cId);
        if (not Empty(cStat)) then begin
            qTicket.qSet('ti_status', cStat);
        end;
        if (not Empty(cBeschr)) then begin
            qTicket.qSet('ti_beschr', cBeschr);
        end;
        qTicket.qSet('ti_aend_dat', Now());
        lOk := qTicket.SaveData(UPDATE_RECORD);
    finally
        qSqlFree(qTicket);
    end;
 
    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geändert werden');
        exit;
    end;
 
    oWriter.Str('status', 'updated');
end;
 
//------------------------------------------------------------------------------
// DELETE /tickets/v1?id=...  Ticket schließen (Status 9 statt Löschen)
//------------------------------------------------------------------------------
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
    cId    : string;
    lOk    : Boolean;
begin
    cId := oReader.Param('id');
    if (Empty(cId)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
        exit;
    end;
 
    if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        exit;
    end;
 
    lOk    := false;
    qTicket := qSqlInit(oDB, 'TICKETS');
    try
        qTicket.qSet('sys_uid'    , cId);
        qTicket.qSet('ti_status'  , '9');
        qTicket.qSet('ti_aend_dat', Now());
        lOk := qTicket.SaveData(UPDATE_RECORD);
    finally
        qSqlFree(qTicket);
    end;
 
    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
        exit;
    end;
 
    oWriter.Str('status', 'closed');
end;
</syntaxhighlight>
 
== Aufruf mit curl ==
Jeder schreibende Aufruf trägt einen <code>Idempotency-Key</code>. Erzeugen Sie je Vorgang einen neuen Schlüssel, z.B. mit <code>uuidgen</code>, und senden Sie bei einer Wiederholung desselben Vorgangs denselben. Regeln: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].
 
Liste aller offenen Tickets:
 
<syntaxhighlight lang="bash">
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    https://obs.example.com/tickets/v1
</syntaxhighlight>
 
Einzelnes Ticket:
 
<syntaxhighlight lang="bash">
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    "https://obs.example.com/tickets/v1?id=abc-123"
</syntaxhighlight>
 
Neues Ticket anlegen:
 
<syntaxhighlight lang="bash">
curl -X POST \
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
    -H "Content-Type: application/json" \
    -d '{"betreff":"Drucker offline","beschr":"Etage 2, Raum 23"}' \
    https://obs.example.com/tickets/v1
</syntaxhighlight>
 
Ticket aktualisieren:
 
<syntaxhighlight lang="bash">
curl -X PUT \
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Idempotency-Key: 8a1d4f62-0c3b-4b7e-a5d9-2e6f9c0b7a13" \
    -H "Content-Type: application/json" \
    -d '{"id":"abc-123","status":"2"}' \
    https://obs.example.com/tickets/v1
</syntaxhighlight>
 
Ticket schließen:
 
<syntaxhighlight lang="bash">
curl -X DELETE \
    -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    -H "Idempotency-Key: c7e05b9a-6f21-4d8c-b3a4-91d2e8f0a6c5" \
    "https://obs.example.com/tickets/v1?id=abc-123"
</syntaxhighlight>
 
Ohne <code>Idempotency-Key</code> antwortet der Server auf <code>POST</code>, <code>PUT</code> und <code>DELETE</code> mit 400 <code>IDEMPOTENCY_KEY_MISSING</code>, ohne das Skript aufzurufen.
 
== Aufruf aus PHP ==
<syntaxhighlight lang="php">
<?php
$apikey = 'abcdef-ghij-klmn-opqr-stuvwx';
$base  = 'https://obs.example.com/tickets/v1';
 
// Neuer Schlüssel je Vorgang. Für eine Wiederholung denselben Schlüssel erneut übergeben.
function neuerKey() {
    return bin2hex(random_bytes(16));
}
 
function rest($method, $url, $apikey, $body = null, $idemKey = null) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL          , $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
    $headers = ['apikey: ' . $apikey];
    if ($idemKey !== null) {
        $headers[] = 'Idempotency-Key: ' . $idemKey;
    }
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $res    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
 
    $data = json_decode($res, true);
    if ($status >= 400) {
        $code = isset($data['error']['code']) ? $data['error']['code'] : 'HTTP_' . $status;
        throw new Exception($code . ': ' . ($data['error']['message'] ?? ''));
    }
    return $data;
}
 
// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
    'betreff' => 'Drucker offline',
    'beschr'  => 'Etage 2, Raum 23'
], neuerKey());
$id = $neu['id'];
 
// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2'], neuerKey());
 
// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
    echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
 
// Ticket schließen
rest('DELETE', $base . '?id=' . urlencode($id), $apikey, null, neuerKey());
?>
</syntaxhighlight>
 
== Was zeigt das Beispiel? ==
* Lesen, Anlegen, Ändern und Schließen über einen Endpunkt, je Methode eine Prozedur <code>Get</code>, <code>Post</code>, <code>Put</code> und <code>Delete</code>.
* JSON-Körper für umfangreichere Eingaben (<code>POST</code>, <code>PUT</code>), Query-Parameter für einfache Werte (<code>GET</code>, <code>DELETE</code>).
* 400 für fehlenden Körper, 422 für fehlende Felder, 404 für unbekannte Tickets, 201 mit <code>Location</code> beim Anlegen.
* Jeder Schreibvorgang wird über den Rückgabewert von <code>SaveData</code> geprüft. Scheitert er, antwortet das Skript mit 500, und der Server nimmt alle Änderungen zurück.
* Schließen über eine Statusänderung statt physischer Löschung.
* <code>Idempotency-Key</code> bei jedem schreibenden Aufruf, auch aus PHP.
* Host-Beschränkung des Zugangs als zweite Sicherheitsebene neben dem API-Key.
 
== Siehe auch ==
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]]
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4 – Pfad-Parameter (REST-Routing über Templates)]]

Aktuelle Version vom 17. November 2026, 07:23 Uhr

Datensatz anlegen mit JSON-Körper

Dieses Beispiel zeigt einen Endpunkt mit allen vier Grundzugriffen: lesen (GET), anlegen (POST), ändern (PUT) und schließen (DELETE). Ein externer Servicedesk liefert damit Tickets in OBS ein, ruft sie ab, aktualisiert und schließt sie – direkt, ohne Dateiaustausch.

HINWEIS: {{{1}}}

Einrichtung in OBS

  • Server-Profil: TLS-Profil Public-API mit einer Bindung auf Port 443
  • Zugang: Servicedesk-X
    • API-Key: vom System erzeugt
    • Host: servicedesk.example.com. Der Server nimmt Anfragen dieses Zugangs nur von der Adresse an, auf die der Name auflöst; andere Absender erhalten 403.
    • JWT-Authentifizierung: nicht gesetzt
  • Endpunkt: Pfad-Template /tickets/v1, Server Public-API
  • Berechtigung: Zugang Servicedesk-X für den Endpunkt /tickets/v1 freigeschaltet

Endpunkt-Skript

Das Skript enthält je HTTP-Methode eine gleichnamige Prozedur. POST, PUT und DELETE laufen in einer Datenbanktransaktion: Endet das Skript mit einem Status ab 400 oder mit einem Laufzeitfehler, nimmt der Server alle Änderungen zurück. Details: Scripting.

// Schreibt die Felder eines Tickets in das Objekt, das der Aufrufer geöffnet hat
procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
                        const cOffset: string);
begin
    oWriter.Str ('id'     , qTicket.A2UID());
    oWriter.Str ('nr'     , qTicket.A2C('ti_nr'));
    oWriter.Str ('betreff', qTicket.A2C('ti_betreff'));
    oWriter.Str ('status' , qTicket.A2C('ti_status'));
    oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
    // Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
    oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;

//------------------------------------------------------------------------------
// GET /tickets/v1?id=...   einzelnes Ticket
// GET /tickets/v1          alle offenen Tickets
//------------------------------------------------------------------------------
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql     : string;
    qData    : TxFQuery;
    cId      : string;
    cOffset  : string;
    lGefunden: Boolean;
begin
    cId     := oReader.Param('id');
    cOffset := oReader.Offset();

    if (not Empty(cId)) then begin
        lGefunden := false;
        cSql := 'SELECT * FROM TICKETS WHERE sys_uid = ' + DB_SqlVal(cId, 'C');
        if (DB_SOpen(oDB, cSql, qData)) then begin
            if (not qData.EoF) then begin
                _TicketFelder(oWriter, qData, cOffset);
                lGefunden := true;
            end;
        end;
        DB_Close(qData);

        if (not lGefunden) then begin
            oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        end;
    end else begin
        // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
        oWriter.RootArr();
        cSql := 'SELECT * FROM TICKETS' +
                ' WHERE ti_status <> ' + DB_SqlVal('9', 'C') +
                ' ORDER BY ti_aend_dat DESC';
        if (DB_SOpen(oDB, cSql, qData)) then begin
            while (not qData.EoF) do begin
                oWriter.ObjBegin('');
                    _TicketFelder(oWriter, qData, cOffset);
                oWriter.ObjEnd;
                qData.Next();
            end;
        end;
        DB_Close(qData);
    end;
end;

//------------------------------------------------------------------------------
// POST /tickets/v1         neues Ticket anlegen
// Körper: {"betreff":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket : TqSQL;
    cId     : string;
    cBetreff: string;
    cBeschr : string;
    lOk     : Boolean;
begin
    // Kein Körper ist 400, ein fehlendes Feld 422
    if (not oReader.HasBody()) then begin
        oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
        exit;
    end;

    cBetreff := '';
    cBeschr  := '';
    oReader.Str('betreff', cBetreff);
    oReader.Str('beschr' , cBeschr);

    if (Empty(cBetreff)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "betreff" fehlt');
        exit;
    end;

    cId := GetNewId(oDB);

    lOk     := false;
    qTicket := qSqlInit(oDB, 'TICKETS');
    qTicket.lNoSysUID := true;
    try
        qTicket.qSet('sys_uid'    , cId);
        qTicket.qSet('ti_nr'      , DB_NeuNum(oDB, 'TICKETS', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
        qTicket.qSet('ti_betreff' , cBetreff);
        qTicket.qSet('ti_beschr'  , cBeschr);
        qTicket.qSet('ti_status'  , '1');
        qTicket.qSet('ti_anl_dat' , Now());
        qTicket.qSet('ti_aend_dat', Now());
        // Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
        lOk := qTicket.SaveData(NEW_RECORD);
    finally
        qSqlFree(qTicket);
    end;

    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht angelegt werden');
        exit;
    end;

    oWriter.Str('id'    , cId);
    oWriter.Str('status', 'created');
    oWriter.Status(201);
    oWriter.Header('Location', '/tickets/v1?id=' + cId);
end;

//------------------------------------------------------------------------------
// PUT /tickets/v1          Ticket aktualisieren
// Körper: {"id":"...", "status":"...", "beschr":"..."}
//------------------------------------------------------------------------------
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
    lOk    : Boolean;
    cId    : string;
    cStat  : string;
    cBeschr: string;
begin
    if (not oReader.HasBody()) then begin
        oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
        exit;
    end;

    cId     := '';
    cStat   := '';
    cBeschr := '';
    oReader.Str('id'    , cId);
    oReader.Str('status', cStat);
    oReader.Str('beschr', cBeschr);

    if (Empty(cId)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Feld "id" fehlt');
        exit;
    end;

    if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        exit;
    end;

    // Ändern: qSqlInit mit sys_uid als Schreib-Index
    lOk     := false;
    qTicket := qSqlInit(oDB, 'TICKETS');
    try
        qTicket.qSet('sys_uid', cId);
        if (not Empty(cStat)) then begin
            qTicket.qSet('ti_status', cStat);
        end;
        if (not Empty(cBeschr)) then begin
            qTicket.qSet('ti_beschr', cBeschr);
        end;
        qTicket.qSet('ti_aend_dat', Now());
        lOk := qTicket.SaveData(UPDATE_RECORD);
    finally
        qSqlFree(qTicket);
    end;

    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geändert werden');
        exit;
    end;

    oWriter.Str('status', 'updated');
end;

//------------------------------------------------------------------------------
// DELETE /tickets/v1?id=...  Ticket schließen (Status 9 statt Löschen)
//------------------------------------------------------------------------------
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
    cId    : string;
    lOk    : Boolean;
begin
    cId := oReader.Param('id');
    if (Empty(cId)) then begin
        oWriter.Error(422, 'VALIDATION_FAILED', 'Parameter "id" fehlt');
        exit;
    end;

    if (not DB_LSeek(oDB, 'TICKETS', 'sys_uid = ' + DB_SqlVal(cId, 'C'))) then begin
        oWriter.Error(404, 'NOT_FOUND', 'Ticket nicht gefunden');
        exit;
    end;

    lOk     := false;
    qTicket := qSqlInit(oDB, 'TICKETS');
    try
        qTicket.qSet('sys_uid'    , cId);
        qTicket.qSet('ti_status'  , '9');
        qTicket.qSet('ti_aend_dat', Now());
        lOk := qTicket.SaveData(UPDATE_RECORD);
    finally
        qSqlFree(qTicket);
    end;

    if (not lOk) then begin
        oWriter.Error(500, 'INTERNAL_ERROR', 'Ticket konnte nicht geschlossen werden');
        exit;
    end;

    oWriter.Str('status', 'closed');
end;

Aufruf mit curl

Jeder schreibende Aufruf trägt einen Idempotency-Key. Erzeugen Sie je Vorgang einen neuen Schlüssel, z.B. mit uuidgen, und senden Sie bei einer Wiederholung desselben Vorgangs denselben. Regeln: HTTP-Schnittstelle.

Liste aller offenen Tickets:

curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     https://obs.example.com/tickets/v1

Einzelnes Ticket:

curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     "https://obs.example.com/tickets/v1?id=abc-123"

Neues Ticket anlegen:

curl -X POST \
     -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     -H "Idempotency-Key: 3f2b8c1e-7d4a-4e9b-9c0f-5a6d2e1b8f47" \
     -H "Content-Type: application/json" \
     -d '{"betreff":"Drucker offline","beschr":"Etage 2, Raum 23"}' \
     https://obs.example.com/tickets/v1

Ticket aktualisieren:

curl -X PUT \
     -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     -H "Idempotency-Key: 8a1d4f62-0c3b-4b7e-a5d9-2e6f9c0b7a13" \
     -H "Content-Type: application/json" \
     -d '{"id":"abc-123","status":"2"}' \
     https://obs.example.com/tickets/v1

Ticket schließen:

curl -X DELETE \
     -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
     -H "Idempotency-Key: c7e05b9a-6f21-4d8c-b3a4-91d2e8f0a6c5" \
     "https://obs.example.com/tickets/v1?id=abc-123"

Ohne Idempotency-Key antwortet der Server auf POST, PUT und DELETE mit 400 IDEMPOTENCY_KEY_MISSING, ohne das Skript aufzurufen.

Aufruf aus PHP

<?php
$apikey = 'abcdef-ghij-klmn-opqr-stuvwx';
$base   = 'https://obs.example.com/tickets/v1';

// Neuer Schlüssel je Vorgang. Für eine Wiederholung denselben Schlüssel erneut übergeben.
function neuerKey() {
    return bin2hex(random_bytes(16));
}

function rest($method, $url, $apikey, $body = null, $idemKey = null) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL           , $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
    $headers = ['apikey: ' . $apikey];
    if ($idemKey !== null) {
        $headers[] = 'Idempotency-Key: ' . $idemKey;
    }
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $res    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($res, true);
    if ($status >= 400) {
        $code = isset($data['error']['code']) ? $data['error']['code'] : 'HTTP_' . $status;
        throw new Exception($code . ': ' . ($data['error']['message'] ?? ''));
    }
    return $data;
}

// Neues Ticket anlegen
$neu = rest('POST', $base, $apikey, [
    'betreff' => 'Drucker offline',
    'beschr'  => 'Etage 2, Raum 23'
], neuerKey());
$id = $neu['id'];

// Status aktualisieren
rest('PUT', $base, $apikey, ['id' => $id, 'status' => '2'], neuerKey());

// Liste auslesen
$alle = rest('GET', $base, $apikey);
foreach ($alle as $t) {
    echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}

// Ticket schließen
rest('DELETE', $base . '?id=' . urlencode($id), $apikey, null, neuerKey());
?>

Was zeigt das Beispiel?

  • Lesen, Anlegen, Ändern und Schließen über einen Endpunkt, je Methode eine Prozedur Get, Post, Put und Delete.
  • JSON-Körper für umfangreichere Eingaben (POST, PUT), Query-Parameter für einfache Werte (GET, DELETE).
  • 400 für fehlenden Körper, 422 für fehlende Felder, 404 für unbekannte Tickets, 201 mit Location beim Anlegen.
  • Jeder Schreibvorgang wird über den Rückgabewert von SaveData geprüft. Scheitert er, antwortet das Skript mit 500, und der Server nimmt alle Änderungen zurück.
  • Schließen über eine Statusänderung statt physischer Löschung.
  • Idempotency-Key bei jedem schreibenden Aufruf, auch aus PHP.
  • Host-Beschränkung des Zugangs als zweite Sicherheitsebene neben dem API-Key.

Siehe auch