DOCLimbasREST

From Limbas Wiki

Jump to: navigation, search

Basis-URL

Die Rest-Schnittstelle in Limbas lässt sich über folgende URL aufrufen. <limbasroot>/dependent/rest

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.

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 möglich 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

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