Zum Inhalt springen

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

Aus OBS Wiki
Rademacker (Diskussion | Beiträge)
Keine Bearbeitungszusammenfassung
MINERVA-Rademacker (Diskussion | Beiträge)
Überschrift an den neuen Titel angeglichen, Links auf die neuen Titel umgestellt, Umlaute in Kommentaren und Meldungstexten [Volltext ersetzt]
 
(4 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Referenz}}
= Datensatz anlegen mit JSON-Körper =


=Beispiel 3: Datensatz anlegen mit JSON-Body=
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.


Dieses Beispiel zeigt einen Endpunkt mit allen vier CRUD-Zugriffen (GET, POST, PUT und - anstelle von DELETE - PATCH, siehe den Hinweis beim Schliessen). Es geht um Tickets eines externen Servicedesks, der Tickets ueber den OBS REST-Server in OBS einliefern, abrufen, aktualisieren und schliessen kann.
{{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]].}}


{{Hinweis|Dieses Beispiel adressiert ein einzelnes Ticket über einen Query-Parameter (''?id...''). Alternativ lässt sich dieselbe Ressource über ein Pfad-Template wie ''/tickets/{id}'' ansprechen; die ID steht dann als ''oReader.Path('id')'' bereit. Ein vollständiges Beispiel dazu zeigt [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4 - Pfad-Parameter]].}}
== Einrichtung in OBS ==
 
* '''Server-Profil:''' TLS-Profil ''Public-API'' mit einer Bindung auf Port 443
==Einrichtung in OBS==
 
* '''Server-Profil:''' Standard-TLS-Profil ''Public-API'', Bindung 0.0.0.0:443
* '''Zugang:''' ''Servicedesk-X''
* '''Zugang:''' ''Servicedesk-X''
** API-Key: zufaellig generiert
** '''API-Key:''' vom System erzeugt
** Host: ''servicedesk.kunde.de'' (DNS-gebunden, IP-Zugriff wird abgelehnt)
** '''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: nicht aktiv
** '''JWT-Authentifizierung:''' nicht gesetzt
* '''Endpunkt:''' ''tickets/v1'', Profil ''Public-API''
* '''Endpunkt:''' '''Pfad-Template''' <code>/tickets/v1</code>, '''Server''' ''Public-API''
* '''Berechtigung:''' Zugang ''Servicedesk-X'' fuer Endpunkt ''tickets/v1'' freigeschaltet
* '''Berechtigung:''' Zugang ''Servicedesk-X'' für den Endpunkt <code>/tickets/v1</code> freigeschaltet
 
==Endpunkt-Skript ''tickets/v1''==


<syntaxhighlight lang="pascal" line>
== 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]].
// Hilfsprozedur: die FELDER eines Tickets. Sie bekommt den Writer und schreibt
// in das Objekt, das der Aufrufer geoeffnet hat - einmal als Listeneintrag,
// einmal in die Wurzel. Ein Helfer, der ein Fragment als String zurueckgibt,
// waere der alte Weg; dabei ging die Reihenfolge im Zusammenbau verloren.
//------------------------------------------------------------------------------


<syntaxhighlight lang="delphi">
// Schreibt die Felder eines Tickets in das Objekt, das der Aufrufer geöffnet hat
procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
procedure _TicketFelder(oWriter: TxRestWriter; qTicket: TxFQuery;
                         const cOffset: string);
                         const cOffset: string);
Zeile 35: Zeile 29:
     oWriter.Str ('status' , qTicket.A2C('ti_status'));
     oWriter.Str ('status' , qTicket.A2C('ti_status'));
     oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
     oWriter.Str ('beschr' , qTicket.A2C('ti_beschr'));
     // Zeitpunkte gehen als ISO-8601 MIT OFFSET ueber die Leitung, nicht im
     // Zeitpunkt als ISO 8601 mit Offset des Servers; leeres Datum ergibt null
    // SQL-Format: DTToSQL liefert 'JJJJ-MM-TT hh:mm:ss' ohne Zeitzone, und der
    // Konsument muss dann raten, in welcher er steht. RestIsoFromDate nimmt den
    // Offset des Servers dazu. Ein leeres Datum ergibt null, nicht 1899.
     oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
     oWriter.StrN('aenderung', RestIsoFromDate(qTicket.A2D('ti_aend_dat'), cOffset));
end;
end;
// Fuer den Body-Zugriff und fuer Fehlerantworten braucht es keine eigenen
// Hilfsfunktionen mehr: oReader liest typisiert, oWriter.Error baut die
// vollstaendige Fehlerhuelle samt traceId.


//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// GET   /tickets/v1?id=...  - einzelnes Ticket
// GET /tickets/v1?id=...  einzelnes Ticket
// GET   /tickets/v1          - alle offenen Tickets
// GET /tickets/v1          alle offenen Tickets
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cSql    : string;
var cSql    : string;
Zeile 59: Zeile 45:
begin
begin
     cId    := oReader.Param('id');
     cId    := oReader.Param('id');
    // Der Offset des Servers geht in jeden Zeitstempel der Antwort.
     cOffset := oReader.Offset();
     cOffset := oReader.Offset();


     if (not Empty(cId)) then begin
     if (not Empty(cId)) then begin
         lGefunden := false;
         lGefunden := false;
         cSql := 'SELECT * FROM tickets WHERE sys_uid = ' + DB_SQLVal(cId);
         cSql := 'SELECT * FROM TICKETS WHERE sys_uid = ' + DB_SqlVal(cId, 'C');
         if (DB_SOpen(oDB, cSql, qData)) then begin
         if (DB_SOpen(oDB, cSql, qData)) then begin
            // EoF gehoert dazu: DB_SOpen sagt nur, dass die ABFRAGE lief.
             if (not qData.EoF) then begin
             if (not qData.EoF) then begin
                 _TicketFelder(oWriter, qData, cOffset);
                 _TicketFelder(oWriter, qData, cOffset);
Zeile 78: Zeile 62:
         end;
         end;
     end else begin
     end else begin
         // Die Liste ist eine nackte Liste. RootArr steht vor der Abfrage:
         // Liste: RootArr vor der Abfrage, kein Treffer ergibt eine leere Liste
        // kein Treffer heisst leere Liste, nicht leeres Objekt.
         oWriter.RootArr();
         oWriter.RootArr();
         cSql := 'SELECT * FROM tickets WHERE ti_status <> "9" ORDER BY ti_aend_dat DESC';
         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
         if (DB_SOpen(oDB, cSql, qData)) then begin
             while (not qData.EoF) do begin
             while (not qData.EoF) do begin
Zeile 95: Zeile 80:


//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// POST /tickets/v1         - neues Ticket anlegen
// POST /tickets/v1         neues Ticket anlegen
// Body: { "betreff":"...", "beschr":"..." }
// Körper: {"betreff":"...", "beschr":"..."}
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Post(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket : TqSQL;
var qTicket : TqSQL;
     cId    : string;
     cId    : string;
     cBetreff: string;
     cBetreff: string;
Zeile 106: Zeile 90:
     lOk    : Boolean;
     lOk    : Boolean;
begin
begin
     // HasBody unterscheidet "kein Koerper" von "Koerper ohne das Feld" - das
     // Kein Körper ist 400, ein fehlendes Feld 422
    // erste ist ein 400, das zweite ein 422.
     if (not oReader.HasBody()) then begin
     if (not oReader.HasBody()) then begin
         oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
         oWriter.Error(400, 'BAD_REQUEST', 'JSON-Body erforderlich');
Zeile 125: Zeile 108:
     cId := GetNewId(oDB);
     cId := GetNewId(oDB);


     xTicket := qSqlInit(oDB, 'tickets');
     lOk    := false;
     xTicket.lNoSysUID := True;
    qTicket := qSqlInit(oDB, 'TICKETS');
     qTicket.lNoSysUID := true;
     try
     try
         xTicket.qSet('sys_uid'    , cId);
         qTicket.qSet('sys_uid'    , cId);
         xTicket.qSet('ti_nr'      , DB_NeuNum(oDB, 'tickets', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
         qTicket.qSet('ti_nr'      , DB_NeuNum(oDB, 'TICKETS', 'ti_nr', NEUNUM_HOLE, '', '', 1, 999999, '0'));
         xTicket.qSet('ti_betreff' , cBetreff);
         qTicket.qSet('ti_betreff' , cBetreff);
         xTicket.qSet('ti_beschr'  , cBeschr);
         qTicket.qSet('ti_beschr'  , cBeschr);
         xTicket.qSet('ti_status'  , '1');
         qTicket.qSet('ti_status'  , '1');
         xTicket.qSet('ti_anl_dat' , Now());
         qTicket.qSet('ti_anl_dat' , Now());
         xTicket.qSet('ti_aend_dat', Now());
         qTicket.qSet('ti_aend_dat', Now());
         // SaveData liefert einen Boolean. Ein SQL-Fehler - etwa Duplicate entry
         // Ein Schreibfehler wirft keine Exception - nur der Rückgabewert zeigt ihn
        // auf einem eindeutigen Index - wirft KEINE Exception und steht in
         lOk := qTicket.SaveData(NEW_RECORD);
        // keinem Protokoll. Ohne diese Auswertung antwortet der Endpunkt mit
        // 201, ohne etwas angelegt zu haben.
         lOk := xTicket.SaveData(NEW_RECORD);
     finally
     finally
         qSqlFree(xTicket);
         qSqlFree(qTicket);
     end;
     end;


Zeile 156: Zeile 137:


//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// PUT   /tickets/v1          - Ticket aktualisieren
// PUT /tickets/v1          Ticket aktualisieren
// Body: { "id":"...", "status":"...", "beschr":"..." }
// Körper: {"id":"...", "status":"...", "beschr":"..."}
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Put(oReader: TxRestReader; oWriter: TxRestWriter);
var xTicket: TqSQL;
var qTicket: TqSQL;
     lOk    : Boolean;
     lOk    : Boolean;
     cId    : string;
     cId    : string;
Zeile 184: Zeile 164:
     end;
     end;


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


     // Zum Aendern qSqlInit mit sys_uid, nicht qSqlRead: qSqlRead liest den
     // Ändern: qSqlInit mit sys_uid als Schreib-Index
     // Altsatz und schreibt nur Aenderungen - ein unveraenderter Wert erzeugt
     lOk     := false;
     // gar kein Write und SaveData liefert False.
     qTicket := qSqlInit(oDB, 'TICKETS');
     xTicket := qSqlInit(oDB, 'tickets');
    xTicket.qSet('sys_uid', cId);
     try
     try
         if (not Empty(cStat))   then xTicket.qSet('ti_status' , cStat);
        qTicket.qSet('sys_uid', cId);
         if (not Empty(cBeschr)) then xTicket.qSet('ti_beschr' , cBeschr);
         if (not Empty(cStat)) then begin
         xTicket.qSet('ti_aend_dat', Now());
            qTicket.qSet('ti_status', cStat);
         lOk := xTicket.SaveData(UPDATE_RECORD);
        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
     finally
         qSqlFree(xTicket);
         qSqlFree(qTicket);
     end;
     end;


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


//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
// PATCH /tickets/v1?id=...   - Ticket schliessen (Soft-Delete via Status=9)
// DELETE /tickets/v1?id=... Ticket schließen (Status 9 statt Löschen)
//
// NICHT als DELETE: 'Delete' ist in der Skriptsprache eine Standardprozedur,
// eine eigene Prozedur dieses Namens laesst sich nicht uebersetzen. Solange das
// so ist, laeuft ein Loeschen ueber PATCH oder POST. Siehe den Hinweis unten.
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
 
procedure Delete(oReader: TxRestReader; oWriter: TxRestWriter);
procedure Patch(oReader: TxRestReader; oWriter: TxRestWriter);
var qTicket: TqSQL;
var xTicket: TqSQL;
     cId    : string;
     cId    : string;
     lOk    : Boolean;
     lOk    : Boolean;
Zeile 230: Zeile 208:
     end;
     end;


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


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


Zeile 254: Zeile 233:
</syntaxhighlight>
</syntaxhighlight>


{{Achtung|'''Ein DELETE-Endpunkt kann derzeit kein Skript haben.''' Der Server
== Aufruf mit curl ==
ruft die Prozedur, die genauso heisst wie das HTTP-Verb - fuer DELETE also
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]].
<code>Delete</code>. Dieser Name ist in der Skriptsprache belegt
(Standardprozedur zum Loeschen aus einer Zeichenkette), und die Deklaration
laesst sich nicht uebersetzen; die Meldung nennt dabei nur die Zeile, nicht die
Ursache. Bis das geloest ist: das Loeschen als <code>PATCH</code> oder
<code>POST</code> mit einer Aktion abbilden. Das Abmelden am JWT-Endpunkt ist
davon nicht betroffen - es laeuft als DELETE '''ohne''' Skript vollstaendig in
der Engine.}}
 
==Aufruf mit curl==


Liste aller offenen Tickets:
Liste aller offenen Tickets:


curl -H "apikey: [API-KEY]" https://api.meinserver.de/tickets/v1
<syntaxhighlight lang="bash">
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    https://obs.example.com/tickets/v1
</syntaxhighlight>


Einzelnes Ticket:
Einzelnes Ticket:


curl -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"
<syntaxhighlight lang="bash">
curl -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" \
    "https://obs.example.com/tickets/v1?id=abc-123"
</syntaxhighlight>


Neues Ticket anlegen:
Neues Ticket anlegen:


curl -X POST -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
<syntaxhighlight lang="bash">
      -d "{\"betreff\":\"Drucker offline\",\"beschr\":\"Etage 2, Raum 23\"}" ^
curl -X POST \
      https://api.meinserver.de/tickets/v1
    -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:
Ticket aktualisieren:


curl -X PUT -H "apikey: [API-KEY]" -H "Content-Type: application/json" ^
<syntaxhighlight lang="bash">
      -d "{\"id\":\"abc-123\",\"status\":\"2\"}" ^
curl -X PUT \
      https://api.meinserver.de/tickets/v1
    -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 schliessen:
Ticket schließen:


curl -X PATCH -H "apikey: [API-KEY]" "https://api.meinserver.de/tickets/v1?id=abc-123"
<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>


==Aufruf aus PHP==
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.


<syntaxhighlight lang="php" line>
== Aufruf aus PHP ==
<syntaxhighlight lang="php">
<?php
<?php
$apikey = '[API-KEY]';
$apikey = 'abcdef-ghij-klmn-opqr-stuvwx';
$base  = 'https://api.meinserver.de/tickets/v1';
$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) {
function rest($method, $url, $apikey, $body = null, $idemKey = null) {
     $ch = curl_init();
     $ch = curl_init();
     curl_setopt($ch, CURLOPT_URL          , $url);
     curl_setopt($ch, CURLOPT_URL          , $url);
Zeile 303: Zeile 300:
     curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
     curl_setopt($ch, CURLOPT_CUSTOMREQUEST , $method);
     $headers = ['apikey: ' . $apikey];
     $headers = ['apikey: ' . $apikey];
    if ($idemKey !== null) {
        $headers[] = 'Idempotency-Key: ' . $idemKey;
    }
     if ($body !== null) {
     if ($body !== null) {
         $headers[] = 'Content-Type: application/json';
         $headers[] = 'Content-Type: application/json';
Zeile 308: Zeile 308:
     }
     }
     curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
     curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
     $res = curl_exec($ch);
     $res   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
     curl_close($ch);
     curl_close($ch);
     return json_decode($res, true);
 
     $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;
}
}


Zeile 317: Zeile 324:
     'betreff' => 'Drucker offline',
     'betreff' => 'Drucker offline',
     'beschr'  => 'Etage 2, Raum 23'
     'beschr'  => 'Etage 2, Raum 23'
]);
], neuerKey());
$id = $neu['id'];
$id = $neu['id'];


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


// Liste auslesen
// Liste auslesen
Zeile 328: Zeile 335:
     echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
     echo $t['nr'] . ' - ' . $t['betreff'] . PHP_EOL;
}
}
// Ticket schließen
rest('DELETE', $base . '?id=' . urlencode($id), $apikey, null, neuerKey());
?>
?>
</syntaxhighlight>
</syntaxhighlight>


==Was zeigt das Beispiel?==
== 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.


* Saubere Trennung der CRUD-Methoden in einem Endpunkt.
== Siehe auch ==
* Verwendung des JSON-Body fuer komplexere Eingangsdaten (POST, PUT).
* [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]
* Verwendung von Query-Parametern fuer einfache Werte (GET, PATCH).
* [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]]
* Soft-Delete ueber Status-Aenderung statt physischer Loeschung - und warum er als PATCH und nicht als DELETE laeuft.
* [[OBS/Kostenpflichtige Module/REST-Server/Endpunkte|Endpunkte]]
* Eindeutige Audit-UIDs (''Y00CXXXXxx'') fuer jeden DB-Zugriff zur Nachvollziehbarkeit.
* [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]]
* Host-gebundener Zugang als zweite Sicherheitsebene neben dem API-Key.
* [[OBS/Kostenpflichtige Module/REST-Server/Beispiele/Pfad-Parameter|Beispiel 4 – Pfad-Parameter (REST-Routing über Templates)]]
* Alternativ: ID per Pfad-Parameter statt Query-Parameter (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel4|Beispiel 4]]).

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