REST Schnittstelle

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

1. Abfrage auf gesamte Tabelle: METHOD /tabellenname
2. Abfrage auf einzelnen Datensatz: METHOD /tabellenname/datensatz-id
3. 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.

GET /kontakte?$page[count]=20&$page[number]=3 

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.

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.

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.

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“.

{"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.

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.

PATCH /kunden/1/boss
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx
{ 
 "data": { "id": "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.

PATCH /kunden/1/kontakte
Content-Type: application/json
Authorization: Basic xxxxxxxxxxxxxxxxxxxx 
{
 "data": [
   { "id": "1" },
   { "id": "2" }
 ]
}

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" }
     ]
}