GraphQL LivingAPI

Bemerkung

Diese Seite ist für Entwickler gedacht. Manche Links leiten auf englischsprachige Webseiten weiter und diese Seiten sind meist für Entwickler geschrieben.

Mithilfe der GraphQL LivingAPI können Sie in jeder Sprache, die einen Https Client unterstützt, mit LivingApps interagieren.

Die GraphQL LivingAPI (GQL LAPI) ermöglicht es auf Daten einer in einem Template definierten Datenquelle zuzugreifen und diese Daten zu aktualisieren. Zusätzlich können neue Datensätze angelegt werden oder existierende gelöscht werden.

Die Antworten sind hierbei immer gültiges JSON.

Bemerkung

Die LivingApps Daten werden als JSON zurückgegeben und nicht wie beim Python SDK oder Javascript SDK als UL4on übergeben. Dadurch sind GQL LAPI nutzende Anwendungen unabhängiger von LivingAPI und UL4 Updates als zuvor. Falls es durch ein Update zu einer Veränderung an dem Aufbau der LivingAPI kommt, so werden betroffene Felder mit polyfills versehen und als deprecated markiert. Von da an haben Sie noch 90 Tage Zeit die Anwendung an die neue API anzupassen.

Bemerkung

Auf dieser Seite wird nicht auf die allgemeine Nutzung von GraphQL eingegangen. Falls Sie GraphQL noch nicht kennen, sehen Sie sich folgende Seite an.

Einloggen

Die GQL LAPI unterstützt zwei Einloggmöglichkeiten. Zum einen können der Nutzername und das Passwort mit jedem Request mitgeschickt werden. Zum anderen wird der OpenId-Connect Standard unterstützt.

Ersteres eignet sich besonders gut für Backend oder Entwicklungssetups.

Zweiteres benötigt Zugang zu einem von LivingApps unterstützten OIDC (OpenId-Connect) Provider. Wenden Sie sich dafür bitte an unser Team.

Login mit Nutzernamen und Passwort

Es müssen die Header

x-la-gql-user
x-la-gql-pwd

gesetzt werden.

Bspw.

curl --request POST \
    --url https://graphql-pwa-la-prod.living-apps.de/ \
    --header 'Content-Type: application/json' \
    --header 'x-la-gql-pwd: <meinGeheimesPasswort>' \
    --header 'x-la-gql-user: <max@mustermann.de>' \
    --data '{"query":"query {...}"}'

Login mit OIDC

Für den Login mit OIDC muss von dem OIDC Provider ein Accesstoken geladen werden. Dieser Accesstoken muss dann im Header „authorization“ mitgeschickt werden.

Bemerkung

Achtung: die Accesstokens haben eine relativ kurze Lebenszeit (bspw. 5 Minuten) und müssen stetig erneuert werden. Bitte machen Sie sich mit OIDCs „Authorization Code Flow“ bekannt.

curl --request POST \
    --url https://graphql-pwa-la-prod.living-apps.de/ \
    --header 'Content-Type: application/json' \
    --header 'authorization: Bearer <your accesstoken>' \
    --data '{"query":"query {...}"}'

Bemerkung

Für Frontendprojekte wie PWAs ist „Login mit OIDC“ zu bevorzugen.

Dokumentation

Wir bieten für die GQL LAPI einen Playground inklusive kurzer englischsprachiger Typendokumentation an. Falls eine deutschsprachige Dokumentation benötigt wird, können die Typen auch in der LivingAPI Dokumentation nachgelesen werden.

GraphQL und Maps

In der LivingAPI werden häufig Maps genutzt aber in GraphQL gibt es keine Maps. Die Alternative sind Listen die Schlüssel-Wert Objekte enthalten. Falls Mapeinträge den Schlüssel selbst als Feld gespeichert haben wird in GraphQL eine Liste der Werte zurückgegeben.

Bspw.

// livingapi
{
    [recordId: string]: Record
}
// graphql
RecordV1[]

Wenn Maps benötigt werden, müssen diese auf der Clientseite aus der (Schlüssel-)Wert Liste bebildet werden.

Antworten Caching

Die GQL LAPI wird innerhalb der LivingLogic für die Entwicklung von Progressive Web Apps genutzt. Progressive Webs Apps sind Webseiten die wie native Anwendungen genutzt werden können. So können auch PWAs bei keiner oder sehr schlechter Internetverbindung genutzt werden. Bei einer sehr schlechten Internetverbindung kann es dazu kommen, dass eine Anfrage abgeschickt wird und die Antwort nicht empfangen werden kann. Um zu verhindern, dass dann Mutations doppelt ausgeführt werden können Anfragen mit einer Id versehen werden. Wird eine Anfrage mit der gleichen Id vom gleichen Nutzer mehrfach innerhalb einer Stunde ausgeführt so wird das Ergebnis der ersten Anfrage zurückgegeben und die GQL LAPI führt den Query oder die Mutation nicht mehr aus.

curl --request POST \
    --url https://my.living-apps.de/gql/ \
    --header 'Content-Type: application/json' \
    --header 'x-la-gql-pwd: <meinGeheimesPasswort>' \
    --header 'x-la-gql-user: <max@mustermann.de>' \
    --header 'x-la-gql-reqid: <meineReqId>' \
    --data '{"query":"mutation {...}"}'