De GraphQL-API van het model

Elke app van Keplin serveert een GraphQL-API op een eigen endpoint. Het schema van die API schrijft u niet met de hand: het wordt uit twee bronnen gegenereerd — de API's die u in de builder bouwt en het gegevensmodel van de app. De tabellen van het model worden GraphQL-types met hun velden en relaties; de enums van het model worden GraphQL-enums; en een Tabel-API maakt van een tabel volledige lees- en schrijfbewerkingen, met filters, sortering en paginering, zonder dat u één regel SQL schrijft.

Deze pagina behandelt het endpoint, de Tabel-API's en de querytaal die zij aan de clients bieden.

#Het endpoint van de app

Alle bewerkingen van een app worden op één enkel GraphQL-endpoint geserveerd:

POST /api/graphql/<adres-van-de-app>

In de voorbeeld-app is dat POST /api/graphql/gestao-clientes. Het verzoek is een JSON met query en variables, zoals bij elke GraphQL-dienst — het tabblad Docs van elke API geeft u kant-en-klare voorbeelden om te kopiëren. Wanneer de app op een eigen adres gepubliceerd is, antwoordt dezelfde dienst ook op /api/graphql van dat adres.

Wie het endpoint mag aanroepen:

Wie aanroept	Hoe die zich authenticeert	Wat die ziet
De schermen van de app	Sessie van de gebruiker van de app (automatisch)	Gepubliceerde API's
Externe systemen	Header x-api-key — zie API-sleutels	Gepubliceerde API's binnen de scope van de sleutel
Wie bouwt	Sessie op het platform	Gepubliceerde API's ÉN concepten (als concept gemarkeerd)
Anoniemen	Niets	Alleen openbare API's

#Een Tabel-API aanmaken

1. Maak een API aan (Nieuwe API) met de naam die als basis voor de bewerkingen gaat dienen — bijvoorbeeld contas.
2. Klik op het tabblad Bouwen, sectie Pipeline, op de knop Tabel. Het blok Tabel neemt de hele pipeline in — het combineert niet met stappen SQL, HTTP of Script.
3. Kies de tabel in de keuzelijst Kies de tabel… — de tabellen verschijnen gegroepeerd per datasource, met zoeken op naam van tabel of van datasource.
4. Schakel de Beschikbaar gestelde acties in en stem de Opgenomen velden af (zie hieronder).
5. Opslaan. Om te publiceren zijn een gekozen tabel en ten minste één actieve actie nodig.

#Beschikbaar gestelde acties

Elke actieve actie genereert een bewerking in het schema, met een naam die van de basis is afgeleid — voor de API contas:

Actie	Gegenereerde bewerking	Wat die doet
Select	getContas (query)	Lijst met filters/sortering/paginering. Brengt countContas mee, het totaal.
Insert	addContas (mutation)	Maakt een rij aan.
Update	updateContas (mutation)	Werkt een rij bij op de primaire sleutel — gedeeltelijk: wijzigt alleen wat u meestuurt.
Delete	deleteContas (mutation)	Verwijdert een rij op de primaire sleutel en geeft true terug.

De regel Openbare toegang (zonder sessie) bepaalt, actie voor actie, wat de openbare schermen mogen aanroepen — details in Openbare API's.

#Opgenomen velden

De boom Opgenomen velden bepaalt de vorm van het antwoord: vink de velden uit die u niet beschikbaar wilt stellen, en klap de navigatievelden uit om gerelateerde entiteiten op te nemen — recursief, als in een visuele GraphQL-editor. In een API contas zorgt het uitklappen van de navigator contactos ervoor dat de clients de contactpersonen van elke account in dezelfde aanroep kunnen opvragen.

#Gegevens lezen: filters, sortering, paginering

De lijstquery aanvaardt vier argumenten: where, order, take en skip. Een volledig voorbeeld in de app Klantenbeheer:

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

#Het argument where

Elk filterbaar veld aanvaardt operatoren afhankelijk van het type:

Type veld	Operatoren
Tekst (en enums)	eq, neq, contains, startsWith, endsWith, gt, gte, lt, lte, in, nin
Getallen (Int, Float)	eq, neq, gt, gte, lt, lte, in, nin
Boolean	eq, neq
ID	eq, neq, in, nin

En twee combinatoren voor samengestelde voorwaarden: and en or, die lijsten met filters ontvangen.

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

Nuttige regels:

• eq: null vindt de records met een leeg veld; neq: null, de ingevulde.
• Datumbereiken: datums die als ISO-tekst bewaard zijn (bijv. 2026-08-11) sorteren alfabetisch zoals zij in de tijd sorteren, dus zijn gt/lt/gte/ lte op tekst genoeg om bereiken te filteren — dataCriacao: { gte: "2026-01-01", lt: "2026-07-01" }.
• in ontvangt een lijst met waarden; nin sluit die uit.
• De waarden van het filter gaan altijd geparameteriseerd naar de database — een contains met kwaadaardige tekst is geen risico.

#Sorteren en pagineren

• order is een lijst van { veld: ASC } of { veld: DESC } — meerdere items sorteren op meerdere velden, in de opgegeven volgorde.
• take beperkt het aantal rijen (plafond van 10 000 per verzoek) en skip slaat de eerste N over — samen vormen zij de klassieke paginering.

#Het totaal: count

Elke Tabel-API met Select actief krijgt er ook count<Naam> bij, die het totale aantal rijen van DEZELFDE where teruggeeft. Het natuurlijke paar van een gepagineerde tabel is de pagina en het totaal in één bewerking opvragen, met aliassen:

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

Geef bij een filter dezelfde where aan beide velden mee — het totaal telt precies de rijen die de lijst zonder paginering zou teruggeven.

#Gegevens schrijven

• addContas ontvangt de opgenomen velden als argumenten (de verplichte velden van de tabel zijn verplicht in de mutation). In sommige databases is het antwoord de aangemaakte rij; in andere true — het tabblad Docs van de API toont de exacte vorm in uw geval.
• updateContas ontvangt de primaire sleutel (verplicht) en de overige velden als optioneel — het werkt alleen bij wat u meestuurt — en geeft de bijgewerkte rij terug.
• deleteContas ontvangt de primaire sleutel en geeft true terug.

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

#Enums

Een enum stelt een vaste verzameling waarden beschikbaar in het GraphQL-schema — de status van een account, de fase van een kans. U beheert ze op de pagina API's, tabblad Enums:

1. Klik op Nieuwe enum.
2. Geef een naam (bijv. EstadoConta) en, als dat helpt, een beschrijving.
3. Voeg waarden toe met Waarde toevoegen — elke waarde heeft een identificatie (value) en een optioneel label en kleur. De kleur en het label worden door de schermen gebruikt; de value is wat door de API reist.
4. Opslaan.

Een enum gebruikt u op twee plekken: als type van een veld van het model (het veld aanvaardt dan alleen die waarden, en in de filters gedraagt het zich als tekst) en als type van een argument van een API. In het schema zien de clients de enum met zijn waarden — het automatisch aanvullen van de testomgeving stelt ze voor.

#Het schema verkennen in GraphiQL

Het tabblad Testen van elke API bevat GraphiQL — de interactieve omgeving van het endpoint van de app. U schrijft de bewerking links, voert uit, en ziet het antwoord rechts; het automatisch aanvullen kent het hele schema, inclusief de Tabel-bewerkingen. De knop In venster openen geeft u dezelfde omgeving schermvullend.

Omdat u op het platform aangemeld bent, voert GraphiQL uit als een client maar ziet het ook de concepten — elke bewerking in concept verschijnt met de beschrijving "RASCUNHO" in de documentatie van het schema. En het antwoordt over uw werkversie: wat u aan het ontwerpen bent, is wat u aan het testen bent.

#Waarom niet…?

• Waarom zie ik de bewerking getContas niet van buitenaf? Ofwel staat de API in concept (publiceer haar), ofwel is de actie Select niet actief, ofwel heeft uw sleutel dat endpoint niet in de scope.
• Waarom verschijnt een veld niet in het antwoord? Het is niet aangevinkt bij Opgenomen velden — de clients mogen alleen selecteren wat de API opneemt.
• Waarom geeft addContas een true in plaats van de rij? Dat hangt af van de database achter de tabel. Hebt u de rij altijd nodig, laat er dan een getContas op volgen, gefilterd op de sleutel.
• Waarom is het schema veranderd zonder dat ik aan de API's kwam? Het schema wordt uit het model gegenereerd: nieuwe kolommen importeren, een enum wijzigen of een entiteit uitschakelen slaat bij de volgende aanroep door naar de API.