Die GraphQL-API des Modells

Jede App von Keplin liefert eine GraphQL-API an einem eigenen Endpunkt aus. Das Schema dieser API wird nicht von Hand geschrieben: Es wird aus zwei Quellen generiert — den APIs, die Sie im Konstruktor bauen, und dem Datenmodell der App. Die Tabellen des Modells werden zu GraphQL-Typen mit ihren Feldern und Relationen; die Enums des Modells werden zu GraphQL-Enums; und eine Tabellen-API verwandelt eine Tabelle in vollständige Lese- und Schreiboperationen, mit Filtern, Sortierung und Paginierung, ohne dass Sie eine Zeile SQL schreiben.

Diese Seite behandelt den Endpunkt, die Tabellen-APIs und die Abfragesprache, die sie den Clients bieten.

#Der Endpunkt der App

Alle Operationen einer App werden an einem einzigen GraphQL-Endpunkt ausgeliefert:

POST /api/graphql/<endereco-da-app>

In der Beispiel-App: POST /api/graphql/gestao-clientes. Der Request ist ein JSON mit query und variables, wie bei jedem GraphQL-Dienst — der Tab Docs jeder API gibt Ihnen fertige Beispiele zum Kopieren. Wenn die App unter einer eigenen Adresse veröffentlicht ist, antwortet derselbe Dienst auch unter /api/graphql dieser Adresse.

Wer den Endpunkt aufrufen kann:

Wer aufruft	Wie er sich authentifiziert	Was er sieht
Die Bildschirme der App	Sitzung des App-Benutzers (automatisch)	Veröffentlichte APIs
Externe Systeme	Header x-api-key — siehe API-Schlüssel	Veröffentlichte APIs innerhalb des Scopes des Schlüssels
Wer baut	Sitzung auf der Plattform	Veröffentlichte APIs UND Entwürfe (als Entwurf markiert)
Anonyme	Nichts	Nur öffentliche APIs

#Eine Tabellen-API erstellen

1. Erstellen Sie eine API (Neue API) mit dem Namen, der als Basis der Operationen dienen wird — zum Beispiel contas.
2. Klicken Sie im Tab Aufbau, Abschnitt Pipeline, auf den Button Tabelle. Der Tabellen-Block belegt die ganze Pipeline — er lässt sich nicht mit Schritten SQL, HTTP oder Skript kombinieren.
3. Wählen Sie die Tabelle im Selektor Tabelle wählen… — die Tabellen erscheinen nach Datenquelle gruppiert, mit Suche nach Tabellen- oder Datenquellennamen.
4. Aktivieren Sie die Bereitgestellte Aktionen und passen Sie die Enthaltene Felder an (siehe unten).
5. Speichern. Zum Veröffentlichen braucht es eine gewählte Tabelle und mindestens eine aktive Aktion.

#Bereitgestellte Aktionen

Jede aktive Aktion erzeugt eine Operation im Schema, mit dem von der Basis abgeleiteten Namen — für die API contas:

Aktion	Erzeugte Operation	Was sie tut
Select	getContas (Query)	Liste mit Filtern/Sortierung/Paginierung. Bringt countContas mit, die Gesamtzahl.
Insert	addContas (Mutation)	Erstellt eine Zeile.
Update	updateContas (Mutation)	Aktualisiert eine Zeile über den Primärschlüssel — partiell: ändert nur, was Sie senden.
Delete	deleteContas (Mutation)	Löscht eine Zeile über den Primärschlüssel und gibt true zurück.

Die Zeile Öffentlicher Zugriff (ohne Sitzung) steuert, Aktion für Aktion, was die öffentlichen Bildschirme aufrufen dürfen — Details unter Öffentliche APIs.

#Enthaltene Felder

Der Baum Enthaltene Felder definiert die Form der Antwort: Wählen Sie die Felder ab, die Sie nicht exponieren wollen, und klappen Sie die Navigationsfelder aus, um verwandte Entitäten einzuschließen — rekursiv, wie in einem visuellen GraphQL-Editor. Bei einer API contas führt das Ausklappen des Navigators contactos dazu, dass die Clients die Kontakte jedes Kontos im selben Aufruf anfordern können.

#Daten lesen: Filter, Sortierung, Paginierung

Die Listen-Query akzeptiert vier Argumente: where, order, take und skip. Ein vollständiges Beispiel in der App Kundenverwaltung:

query {
  getContas(
    where: { cidade: { eq: "Lisboa" }, estado: { neq: "ARQUIVADA" } }
    order: [{ nome: ASC }]
    take: 20
    skip: 0
  ) {
    id
    nome
    cidade
    contactos {
      nome
      email
    }
  }
}

#Das Argument where

Jedes filterbare Feld akzeptiert Operatoren je nach Typ:

Typ des Feldes	Operatoren
Text (und Enums)	eq, neq, contains, startsWith, endsWith, gt, gte, lt, lte, in, nin
Zahlen (Int, Float)	eq, neq, gt, gte, lt, lte, in, nin
Boolean	eq, neq
ID	eq, neq, in, nin

Und zwei Kombinatoren für zusammengesetzte Bedingungen: and und or, die Listen von Filtern erhalten.

where: {
  or: [
    { cidade: { eq: "Lisboa" } }
    { cidade: { eq: "Porto" } }
  ]
  valorAnual: { gte: 10000 }
}

Nützliche Regeln:

• eq: null findet die Datensätze mit leerem Feld; neq: null die ausgefüllten.
• Datumsintervalle: Als ISO-Text gespeicherte Daten (z. B. 2026-08-11) sortieren alphabetisch so, wie sie zeitlich sortieren, weshalb gt/lt/gte/lte auf Text genügen, um Intervalle zu filtern — dataCriacao: { gte: "2026-01-01", lt: "2026-07-01" }.
• in erhält eine Liste von Werten; nin schließt sie aus.
• Die Werte des Filters gehen immer parametrisiert zur Datenbank — ein contains mit bösartigem Text ist kein Risiko.

#Sortieren und paginieren

• order ist eine Liste von { feld: ASC } oder { feld: DESC } — mehrere Einträge sortieren nach mehreren Feldern, in der angegebenen Reihenfolge.
• take begrenzt die Zahl der Zeilen (Obergrenze 10 000 pro Request) und skip überspringt die ersten N — zusammen ergeben sie die klassische Paginierung.

#Die Gesamtzahl: count

Jede Tabellen-API mit aktivem Select erhält auch count<Name>, das die Gesamtzahl der Zeilen des SELBEN where zurückgibt. Das natürliche Paar einer paginierten Tabelle ist, die Seite und die Gesamtzahl in einer einzigen Operation anzufordern, mit Aliassen:

query {
  items: getContas(take: 10, skip: 0) { id nome }
  total: countContas
}

Mit Filter übergeben Sie beiden Feldern dasselbe where — die Gesamtzahl zählt genau die Zeilen, die die Liste ohne Paginierung zurückgeben würde.

#Daten schreiben

• addContas erhält die enthaltenen Felder als Argumente (die Pflichtfelder der Tabelle sind in der Mutation Pflicht). Bei manchen Datenbanken ist die Antwort die erstellte Zeile; bei anderen true — der Tab Docs der API zeigt die genaue Form in Ihrem Fall.
• updateContas erhält den Primärschlüssel (Pflicht) und die übrigen Felder als optional — es aktualisiert nur, was Sie senden — und gibt die aktualisierte Zeile zurück.
• deleteContas erhält den Primärschlüssel und gibt true zurück.

mutation ($nome: String!, $cidade: String) {
  addContas(nome: $nome, cidade: $cidade) {
    id
    nome
  }
}

#Enums

Ein Enum exponiert eine feste Menge von Werten im GraphQL-Schema — den Status eines Kontos, die Phase einer Verkaufschance. Verwaltet werden sie auf der Seite APIs, Tab Enums:

1. Klicken Sie auf Neues Enum.
2. Geben Sie einen Namen (z. B. EstadoConta) und, wenn es hilft, eine Beschreibung.
3. Fügen Sie Werte mit Wert hinzufügen hinzu — jeder Wert hat einen Bezeichner (value), ein optionales Label und eine optionale Farbe. Farbe und Label werden von den Bildschirmen verwendet; der value ist das, was in der API reist.
4. Speichern.

Ein Enum wird an zwei Stellen verwendet: als Typ eines Feldes des Modells (das Feld akzeptiert dann nur noch diese Werte, und in den Filtern verhält es sich wie Text) und als Argumenttyp einer API. Im Schema sehen die Clients das Enum mit seinen Werten — die Vervollständigung der Testumgebung schlägt sie vor.

#Das Schema im GraphiQL erkunden

Der Tab Test jeder API enthält das GraphiQL — die interaktive Umgebung des Endpunkts der App. Sie schreiben die Operation links, führen aus, und sehen die Antwort rechts; die Vervollständigung kennt das ganze Schema, Tabellen-Operationen eingeschlossen. Der Button In Fenster öffnen gibt Ihnen dieselbe Umgebung im Vollbild.

Da Sie auf der Plattform authentifiziert sind, führt das GraphiQL wie ein Client aus, sieht aber auch die Entwürfe — jede Operation im Entwurf erscheint mit der Beschreibung „RASCUNHO" in der Dokumentation des Schemas. Und es antwortet über Ihre Arbeitsversion: Was Sie gerade entwerfen, ist das, was Sie gerade testen.

#Warum nicht…?

• Warum sehe ich die Operation getContas von außen nicht? Entweder ist die API im Entwurf (veröffentlichen Sie sie), oder die Aktion Select ist nicht aktiv, oder Ihr Schlüssel hat diesen Endpunkt nicht im Scope.
• Warum erscheint ein Feld nicht in der Antwort? Es ist unter Enthaltene Felder nicht markiert — die Clients können nur auswählen, was die API einschließt.
• Warum gibt addContas ein true statt der Zeile zurück? Das hängt von der Datenbank hinter der Tabelle ab. Wenn Sie die Zeile immer brauchen, lassen Sie ein getContas folgen, gefiltert nach dem Schlüssel.
• Warum hat sich das Schema geändert, ohne dass ich die APIs angefasst habe? Das Schema wird aus dem Modell generiert: Neue Spalten zu importieren, ein Enum zu ändern oder eine Entität zu deaktivieren spiegelt sich beim nächsten Aufruf in der API wider.