Schnittstellen REST Schnittstelle Geschätzte Lektüre: 7 Minuten Notiz: Zum Verwenden der REST-Schnittstelle ist mindestens PHP-Version 7.1.0 erforderlich. Basis-URL Die Rest-Schnittstelle in Limbas lässt sich über folgende URL aufrufen. <limbasurl>/dependent/main_rest.php/ Bei Bedarf einer „schöneren“ URL wie z.B. <limbasurl>/api/ kann abhängig von der eigenen Serverkonfiguration ein Redirect in der .htaccess-Datei hinzugefügt werden. In den Umgebungsvariablen muss dann die Einstellung restpath entsprechend angepasst werden. Beispiel: RewriteEngine On RewriteBase / RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^api/?(.*)$ /main_rest.php [NC,QSA] Autorisierung Die Anmeldung in Limbas funktioniert per BASIC Auth. Es reicht daher aus, dem Request den folgenden Header anzuhängen: Authorization: Basic xxxxxxxxxxxxxxxxxxxx Content-Type Limbas akzeptiert als Request-Body bei POST/PATCH/DELETE folgende zwei Content-Typen, die jeweils als Anfrage-Header mitgegeben werden müssen. Content-Type: application/json Content-Type: x-www-form-urlencoded Als Rückgabe erhält man immer ein JSON-Objekt. URL-Struktur Es werden drei URL-Struktur-Typen unterstützt: METHOD = GET / POST / PATCH / DELETE Abfrage auf gesamte Tabelle: METHOD /tabellenname Abfrage auf einzelnen Datensatz: METHOD /tabellenname/datensatz-id Abfrage auf verknüpfte Datensätze eines Datensatzes: METHOD /tabellenname/datensatz-id/verknüpfungsfeld Daten Abfragen (GET) GET Anfragen können an alle drei URL-Struktur-Typen gesendet werden Pagination Erfolgt über den Parameter $page: $page[count] legt fest, wie viele Datensätze pro Seite zurückgegeben werden. $page[number] legt fest, welche Seite zurückgegeben werden soll. Wird der Parameter weggelassen, werden alle Datensätze zurückgegeben. Beispiel GET /kontakte?$page[count]=20&$page[number]=3 teil das Ergebnis in Seiten von jeweils 20 Datensätzen auf und gibt Seite 3 zurück. In der Antwort des Servers werden verwandte Seiten (first, prev, next, last) unter dem Toplevel Eintrag links nach dem HATEOAS-Prinzip angezeigt. Felder begrenzen Erfolgt über den Parameter $fields. Wird dieser nicht gesetzt, werden alle Felder der aktiven Tabelle zurückgegeben. Mögliche Syntaxen: $fields=feld1,feld2: Es werden nur die Felder name und vorname zurückgegeben (Tabelle implizit durch URL definiert) $fields[tabellenname]=feld1,feld2: Gleiche Bedeutung, Tabelle explizit definiert $fields[tabellenname]=*: Alle Felder der Tabelle Sortierung Erfolgt über den Parameter sort. Syntax: $sort=feld1,-feld2: Sortiert zuerst nach feld1 (aufsteigend), dann nach feld2 (absteigend) $sort=tabellenname.feld1,-tabellenname.feld2: Gleiche Bedeutung, Tabelle explizit definiert Filterung Jedes Tabellenfeld kann mit einem oder mehreren Filtern belegt werden. Als Parameter für die Sortierung dienen die jeweiligen Feldnamen einer Tabelle. Folgende Syntaxen sind möglich: feldname=suchwert Das Feld feldname muss genau gleich dem Suchbegriff sein feldname[operator]=suchwert Das Feld feldname wird mit einem bestimmten Operator durchsucht tabellenname[feldname]=suchwert Unterscheidet sich nur durch explizite Angabe der Tabelle tabellenname[feldname][operator]=suchwert Unterscheidet sich nur durch explizite Angabe der Tabelle Operatoren Folgende Operatoren stehen zur Verfügung: Für numerische Werte: eq = Gleich neq = Ungleich lt = Kleiner gleich gt = Größer gleich lte = Kleiner gleich oder gleich gte = Größer gleich oder gleich Für Textwerte eq = Gleich contains = Suchwert kommt in Text vor startswith = Text startet mit Suchwert endswith = Text endet mit Suchwert Archivierung Ist für eine Tabelle die Archivierung aktiviert, werden standardmäßig nur Datensätze zurückgegeben, die nicht archiviert sind. Das kann folgendermaßen angepasst weden: $archived=false Nur nicht-archivierte Datensätze werden zurückgegeben (Standard) $archived=true Nur archivierte Datensätze werden zurückgegeben $archived=all Es werden alle Datensätze zurückgegeben, unabhängig von der Archivierung Gültigkeit Über den Filter „validity“ kann eine mit dem Parameter „validity“ gekennzeichnete Tabelle nach einem Datum gefiltert und somit nur die in diesem Zeitraum gültigen Datensätze angezeigt werden. NULL Werte in den entsprechenden von/bis Feldern werden als gültig betrachtet. Folgende Werte sind zulässig $validity=[DATUM] (es werden gültige Datensätze des angegebenen Datums zurück gegeben) $validity=all (es werden gültige und nicht gültige Datensätze zurück gegeben) $validity=allfrom (es werden gültige und zukünftige Datensätze zurück gegeben) $validity=allto (es werden gültige und vergangene Datensätze zurück gegeben) Datensatz hinzufügen (POST) POST-Anfragen zum Erstellen eines Datensatzes können ausschließlich an URLs des Typs 1 gesendet werden. Die ID wird immer durch Limbas vergeben und kann nicht vorbelegt werden. Zwingend notwendig im Request-Body ist das „data“-Element. Innerhalb des data-Elements werden die zu aktualisierenden Attribute als Key-Value-Paare angegeben, wobei Key der jeweilige Feldname ist. Beispiel Nachfolgend wird ein neuer Kunde erstellt. POST / kunden Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": { "name":“Max Mustermann“ "strasse":"Musterweg 1", "plz":"12345", "ort":"Musterort" } } Rückgabe Als Antwort erhält man den neu angelegten Datensatz. Datensatz aktualisieren (PATCH) Eine PATCH-Anfrage kann ausschließlich auf konkrete Datensätze bezogen werden. Demnach sind nur die URL-Struktur-Typen 2 und 3 zulässig. Zwingend notwendig im Request-Body ist das „data“-Element. Innerhalb des data-Elements werden die zu aktualisierenden Attribute als Key-Value-Paare angegeben, wobei Key der jeweilige Feldname ist. Beispiel Nachfolgend wird die Adresse des Kunden mit der ID 1 aktualisiert. PATCH /kunden/1 Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": { "strasse":"Musterweg 1", "plz":"12345", "ort":"Musterort" } } Rückgabe Als Antwort erhält man den gesamten aktualisierten Datensatz. Datensatz löschen (DELETE) Mit einem DELETE-Request an eine URL des Typs 2 lässt sich ein konkreter Datensatz entfernen. Das Löschen aller Datensätze einer Tabelle auf einmal ist nicht möglich. Beispiel Lösche den Kunden mit der ID 1 DELETE /kunden/1 Authorization: Basic xxxxxxxxxxxxxxxxxxxx Rückgabe 204 – No Content 400 – Deletion failed 404 – Not found Verknüpfungen Verknüpfungen werden immer als Relationsobjekt mit einzigem Attribut „id“. Beispiel Datensatz mit ID 1: {"id":“1“}. Verknüpfungen hinzufügen (POST) Per POST-Request an URLs des Typs 3 lassen sich einem Datensatz Verknüpfungen hinzufügen. Existierende Verknüpfungen werden dabei nicht überschrieben. Beispiel Dem Kunden mit der ID 1 werden die Kontakte mit den IDs 1 und 2 hinzugefügt. POST /kunden/1/kontakte { "data": [ { "id": "1" }, { "id": "2" } ] } Verknüpfungen aktualisieren (PATCH) Per PATCH-Request lassen sich die Verknüpfungen eines Datensatzes aktualisieren. Dabei werden bestehende Verknüpfungen ersetzt. Der PATCH-Aufruf ist jeweils auf zwei Verschiedene Arten möglich: Typ 3: An die Verknüpfung direkt: PATCH /tabellenname/datensatz-id/verknüpfungsfeld Typ 2: Als Attribut per PATCH an den Hauptdatensatz PATCH /tabellenname/datensatz-id Unique-Verknüpfung Bei einer unique-Verknüpfung entsrpicht der Wert von „data“ exakt einem Relationsobjekt. Wird bei einer unique-Verknüpfung anstatt eines Relationsobjekts der Wert null übergeben, wird die Verknüpfung gelöscht. Beispiel Der Kunde kann genau einen Boss haben. Als Boss soll dem Kunden mit der ID 1 nun der Kontaktdatensatz mit der ID 1 zugewiesen werden. Variante 1: PATCH an boss-Relation des Kunden mit der ID 1 PATCH /kunden/1/boss Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": { "id": "1" } } Variante 2: PATCH an den Kunden mit der ID 1 und der Verknüpfung als Attribut PATCH /kunden/1 Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": { "boss": { "data": { "id": "1" } } } } Many-Verknüpfung Bei einer Many-Verknüpfung ist das data-Element ein Array aus Verknüpfungsobjekten. Ist data ein leeres Array, so werden alle Verknüpfungen gelöscht. Beispiel Dem Kunden mit der ID 1 sollen die Kontakte mit den IDs 1 und 2 hinzugefügt werden. Variante 1: PATCH an kontakte-Relation des Kunden mit der ID 1 PATCH /kunden/1/kontakte Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": [ { "id": "1" }, { "id": "2" } ] } Variante 2: PATCH an den Kunden mit der ID 1 und der Verknüpfung als Attribut PATCH /kunden/1 Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": { "kontakte": { "data": [ { "id": "1" }, { "id": "2" } ] } } } Verknüpfungen löschen (DELETE) Äquivalent zum Hinzufügen von Verknüpfungen per POST können diese mit DELETE entfernt werden. In keinem Fall werden dabei ganze Datensätze gelöscht. Unique-Verknüpfungen Bei Unique-Verknüpfungen reicht ein DELETE-Request an die URL des Typs 3 aus, um die entsprechende Verknüpfung zu entfernen. DELETE /kunden/1/boss Authorization: Basic xxxxxxxxxxxxxxxxxxxx Many Verknüpfung Bei Many-Verknüfungen müssen konkrete Datensätze angegeben werden, deren Verknüpfung aufgehoben werden soll. Ein Löschen aller Verknüpfungen auf einmal ist nicht möglich. Entferne die Verknüpfungen vom Kunden mit der ID 1 zu den Kontakten mit den IDs 1 und 2 DELETE /kunden/99 Content-Type: application/json Authorization: Basic xxxxxxxxxxxxxxxxxxxx { "data": [ { "id": "1" }, { "id": "2" } ] }
