GraphQL-API-et for modellen

Hver app i Keplin serverer et GraphQL-API på sitt eget endepunkt. Skjemaet til det API-et skrives ikke for hånd: det genereres fra to kilder — API-ene du lager i builderen og appens datamodell. Tabellene i modellen blir GraphQL-typer med sine felt og relasjoner; enumene i modellen blir GraphQL-enumer; og et Tabell-API forvandler en tabell til komplette lese- og skriveoperasjoner, med filtre, sortering og paginering, uten at du skriver en eneste linje SQL.

Denne siden dekker endepunktet, Tabell-API-ene og spørrespråket de tilbyr klientene.

#Endepunktet til appen

Alle operasjonene i en app serveres på ett enkelt GraphQL-endepunkt:

POST /api/graphql/<adressen-til-appen>

I eksempelappen, POST /api/graphql/gestao-clientes. Forespørselen er en JSON med query og variables, som i enhver GraphQL-tjeneste — fanen Dokumentasjon i hvert API gir deg eksempler klare til å kopieres. Når appen er publisert på en egen adresse, svarer den samme tjenesten også på /api/graphql på den adressen.

Hvem som kan kalle endepunktet:

Hvem kaller	Hvordan de autentiseres	Hva de ser
Skjermene i appen	Økten til brukeren av appen (automatisk)	Publiserte API-er
Eksterne systemer	Headeren x-api-key — se API-nøkler	Publiserte API-er innenfor nøkkelens scope
Den som bygger	Økt på plattformen	Publiserte API-er OG utkast (merket som utkast)
Anonyme	Ingenting	Bare offentlige API-er

#Lage et Tabell-API

1. Lag et API (Ny API) med navnet som skal være basen for operasjonene — for eksempel contas.
2. På fanen Bygg, seksjonen Pipeline, trykk på knappen Tabell. Tabell-blokken opptar hele pipelinen — den kan ikke kombineres med SQL-, HTTP- eller Skript-trinn.
3. Velg tabellen i velgeren Velg tabell… — tabellene vises gruppert per datakilde, med søk på tabell- eller datakildenavn.
4. Aktiver de Eksponerte handlingene og juster de Inkluderte feltene (se nedenfor).
5. Lagre. For å publisere trengs valgt tabell og minst én aktiv handling.

#Eksponerte handlinger

Hver aktiv handling genererer en operasjon i skjemaet, med navnet utledet av basen — for API-et contas:

Handling	Generert operasjon	Hva den gjør
Select	getContas (query)	Liste med filtre/sortering/paginering. Har med seg countContas, totalen.
Insert	addContas (mutation)	Oppretter en rad.
Update	updateContas (mutation)	Oppdaterer en rad via primærnøkkelen — delvis: endrer bare det du sender.
Delete	deleteContas (mutation)	Sletter en rad via primærnøkkelen og returnerer true.

Linjen Offentlig tilgang (uten økt) styrer, handling for handling, hva de offentlige skjermene kan kalle — detaljer i Offentlige API-er.

#Inkluderte felt

Treet Inkluderte felt definerer formen på svaret: fjern haken på feltene du ikke vil eksponere, og utvid navigasjonsfeltene for å inkludere relaterte entiteter — rekursivt, som i en visuell GraphQL-editor. I et API contas gjør en utvidelse av navigatoren contactos at klientene kan be om kontaktene til hver konto i samme kall.

#Lese data: filtre, sortering, paginering

Listespørringen godtar fire argumenter: where, order, take og skip. Et komplett eksempel i appen Kundehåndtering:

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

#Argumentet where

Hvert filtrerbare felt godtar operatorer etter typen:

Feltets type	Operatorer
Tekst (og enumer)	eq, neq, contains, startsWith, endsWith, gt, gte, lt, lte, in, nin
Tall (Int, Float)	eq, neq, gt, gte, lt, lte, in, nin
Boolean	eq, neq
ID	eq, neq, in, nin

Og to kombinatorer for sammensatte betingelser: and og or, som tar imot lister av filtre.

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

Nyttige regler:

• eq: null finner postene med feltet tomt; neq: null, de utfylte.
• Datointervaller: datoer lagret som ISO-tekst (f.eks. 2026-08-11) sorterer alfabetisk slik de sorterer i tid, derfor holder gt/lt/gte/lte på tekst for å filtrere intervaller — dataCriacao: { gte: "2026-01-01", lt: "2026-07-01" }.
• in tar imot en liste av verdier; nin utelukker den.
• Filterverdiene sendes alltid som parametere til databasen — en contains med ondsinnet tekst er ingen risiko.
• contains, startsWith og endsWith søker etter teksten nøyaktig slik den er skrevet: et % eller _ er tekst, ikke et jokertegn, og store og små bokstaver teller ikke i noen database ("ana" finner "Ana").

#Sortere og paginere

• order er en liste av { felt: ASC } eller { felt: DESC } — flere elementer sorterer på flere felt, i den gitte rekkefølgen.
• take begrenser antall rader (tak på 10 000 per forespørsel) og skip hopper over de første N — sammen utgjør de den klassiske pagineringen.

#Totalen: count

Hvert Tabell-API med Select aktiv får også count<Navn>, som returnerer totalt antall rader for det SAMME where. Det naturlige paret for en paginert tabell er å be om siden og totalen i én operasjon, med aliaser:

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

Med filter, send det samme where til begge feltene — totalen teller nøyaktig de radene listen ville returnert uten paginering.

#Skrive data

• addContas tar imot de inkluderte feltene som argumenter (de påkrevde i tabellen er påkrevde i mutationen). I noen databaser er svaret raden som ble opprettet; i andre, true — fanen Dokumentasjon i API-et viser den nøyaktige formen i ditt tilfelle. En ikke-null-kolonne med standardverdi i databasen, eller som databasen genererer, er valgfri: sender du den ikke, gjelder databasens verdi.
• updateContas tar imot primærnøkkelen (påkrevd) og de øvrige feltene som valgfrie — den oppdaterer bare det du sender — og returnerer den oppdaterte raden.
• deleteContas tar imot primærnøkkelen og returnerer true.

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

En dato-og-tid-kolonne uten tidssone (timestamp, datetime) forlater API-et slik den står i databasen, som ISO uten tidssone (2026-09-25T09:30:00): det er tiden som står der, og den kommer likt fram til den som leser den, i hvilken som helst tidssone. En kolonne med bare dagen kommer som dagen (2026-09-25). En kolonne med tidssone (timestamptz, datetimeoffset, timestamp i MySQL) kommer som et tidspunkt, som ISO med tidssone (2026-09-25T09:30:00.000Z), og skjermene viser den i leserens tidssone. En Date som et SQL-trinn i et pipeline-API returnerer, kommer også som ISO med tidssone. Skjermene viser alle på appens språk. En verdi med feil type godtas når det ikke er tvil: «12» i en Int, 1000 i en String, «true» i en Boolean.

Tre regler til for skriving:

• Primærnøkkelen kan også sendes i add. Med en nøkkel som databasen genererer, utelates den; med en naturlig nøkkel (en varekode, en landkode) er det slik posten opprettes.
• En update av en post som ikke finnes, eller som er utenfor omfanget til den som spør, endrer ingenting og returnerer null; en delete under de samme forholdene returnerer false.
• Et avslag fra databasen (gjentatt nøkkel, post med avhengige poster, tomt obligatorisk felt, for lang verdi) kommer frem som en tydelig melding, med feltet når databasen oppgir det.

En forespørsel kan nøste opptil 12 nivåer med relasjoner og bruke opptil 100 aliaser. Relasjoner leses i puljer: rader som etterspørres samtidig, går i én spørring.

#Enumer

En enum eksponerer et fast sett med verdier i GraphQL-skjemaet — statusen til en konto, fasen til en salgsmulighet. De administreres på siden API-er, fanen Enumer:

1. Trykk på Ny enum.
2. Gi den et navn (f.eks. EstadoConta) og, hvis det hjelper, en beskrivelse.
3. Legg til verdier med Legg til verdi — hver verdi har en identifikator (value), og valgfri etikett og farge. Fargen og etiketten brukes av skjermene; value er det som reiser i API-et.
4. Lagre.

En enum brukes på to steder: som typen til et felt i modellen (feltet godtar da bare de verdiene, og i filtrene oppfører det seg som tekst) og som argumenttype i et API. I skjemaet ser klientene enumen med verdiene sine — autofullføringen i testmiljøet foreslår dem.

Når du skriver en enum-verdi, godtar API-et navnet som skjemaet viser, uten anførselstegn (estado: Em_curso), og også verdien slik den er lagret, i anførselstegn (estado: "Em curso"). Det er slik skjemaene og keplin.api.mutate sender den. En verdi som ikke hører til enumen, avvises fortsatt.

#Utforske skjemaet i GraphiQL

Fanen Test i ethvert API inkluderer GraphiQL — det interaktive miljøet for appens endepunkt. Du skriver operasjonen til venstre, kjører, og ser svaret til høyre; autofullføringen kjenner hele skjemaet, Tabell-operasjoner inkludert. Knappen Åpne i vindu gir deg det samme miljøet i fullskjerm.

Siden du er autentisert på plattformen, kjører GraphiQL som en klient, men ser også utkastene — hver operasjon i utkast vises med beskrivelsen «UTKAST» i skjemadokumentasjonen. Og den svarer over din arbeidsversjon: det du designer, er det du tester.

#Hvorfor kan jeg ikke…?

• Hvorfor ser jeg ikke operasjonen getContas utenfra? Enten er API-et i utkast (publiser det), eller handlingen Select er ikke aktiv, eller nøkkelen din har ikke det endepunktet i sitt scope.
• Hvorfor vises ikke et felt i svaret? Det er ikke avmerket i Inkluderte felt — klientene kan bare velge det API-et inkluderer.
• Hvorfor returnerer addContas en true i stedet for raden? Det avhenger av databasen bak tabellen. Når du alltid trenger raden, følg opp med en getContas filtrert på nøkkelen.
• Hvorfor endret skjemaet seg uten at jeg rørte API-ene? Skjemaet genereres fra modellen: å importere nye kolonner, endre en enum eller deaktivere en entitet gjenspeiles i API-et ved neste kall.