API-builderen

Hvert API i Keplin er en GraphQL-operasjon i appen: en query som leser data eller en mutation som skriver dem. Appens egne skjermer, rapportene, arbeidsflytene og eksterne systemer kaller alle de samme API-ene — det du definerer her, er den eneste veien inn og ut for dataene i applikasjonen.

Et API kan ha én av to naturer:

Natur	Hva det er	Hvor det utdypes
Pipeline	En sekvens av trinn (SQL-spørring, HTTP-kall, Skript) som kjører i rekkefølge; resultatet av det siste trinnet er svaret.	Denne siden
Tabell	En enkelt blokk knyttet til en tabell i datamodellen, som genererer lese- og skriveoperasjonene (get/add/update/delete) for deg.	GraphQL-API-et for modellen

Denne siden dekker selve builderen: lage API-et, definere argumenter, sette sammen pipelinen, teste uten å lagre og publisere.

#Hvor API-ene bor

Inne i en app, åpne panelet Kode i sidefeltet. Seksjonen API-er lister opp API-ene som finnes — du kan organisere dem i mapper med Ny mappe — og hvert av dem åpnes som en fane i arbeidsområdet. Appen har også en oversiktsside med den komplette listen, typen og tilstanden til hvert API, og adressen der de serveres.

#Lage et API

1. I panelet Kode, på linjen API-er, trykk på knappen + (Ny API). Knappen Ny API på oversiktssiden tar deg til samme sted: arbeidsområdet i appen.
2. Gi det et Navn. Navnet er GraphQL-feltet klientene skal kalle, så følg regelen: bokstaver, tall og understrek, uten å begynne med tall — for eksempel getOportunidadesPorConta.
3. Trykk på Opprett API. API-et fødes som utkast, og builderen åpnes etterpå — det er der du bestemmer naturen (blokker for SQL, HTTP, skript eller tabell).

#Builderen i et overblikk

Toppteksten i builderen viser navnet, et merke med typen (query, mutation eller tabell) og tilstanden (publisert eller utkast). Til høyre står kommandoene som gjelder hele API-et:

Kommando	Hva den gjør
Publisert	Slår publiseringen på/av. Et API i utkast er bare synlig for den som bygger; eksterne klienter ser det ikke.
Offentlig (uten økt)	Gjør API-et tilgjengelig uten økt eller API-nøkkel — for appens offentlige skjermer. Se Offentlige API-er.
Lagre	Lagrer API-et slik det er. Å lagre er alltid mulig med gyldig navn og gyldige argumenter — halvferdig arbeid lagres like fullt.

Under det er arbeidet delt i tre faner:

Fane	Til hva
Bygg	Identifikasjon, argumenter og pipelinen av trinn.
Test	Kjøre pipelinen som utkast og prøve API-et som en klient.
Dokumentasjon	Eksempler klare til å kopieres for å kalle API-et utenfra.

#Identifikasjon

I seksjonen Identifikasjon definerer du:

• Operasjon — Query — leser data eller Mutation — skriver data. Valget er semantisk og praktisk: mutations ber om bekreftelse før hver testkjøring, fordi de skriver på ordentlig.
• Navn — GraphQL-feltet. Hvis navnet er ugyldig, varsler builderen: «Enkel camelCase: bokstaver, tall og understrek, kan ikke begynne med tall.»

I et Tabell-API finnes det ikke noe operasjonsvalg — operasjonene utledes av CRUD-handlingene du aktiverer i Tabell-blokken.

#Argumenter

Seksjonen Argumenter deklarerer parameterne klientene sender til API-et. Hvert argument har:

Kolonne	Hva det er
Navn	Identifikatoren til argumentet (bokstaver, tall, understrek; begynner ikke med tall).
Type	En av: String, Int, Float, Boolean, ID, JSON, Upload.
Påkr.	Om klienten er nødt til å sende argumentet.
Standard	Verdien som brukes når klienten ikke sender noe.
Testverdi	Bare for knappen Kjør på fanen Test — påvirker ikke klientene.

Inne i pipelinen er argumentene tilgjengelige som :navn i SQL- og HTTP-trinnene, og som input["args"]["navn"] i Skript-trinnet.

#Filer som argument (typen Upload)

Et argument av typen Upload tar imot en fil. I det tilfellet viker kolonnen Standard for valget av lagring: Appens standard bruker standardlagringen; alternativt velger du en av lagringene som er satt opp i appens innstillinger (seksjonen Lagring). Slik trenger ikke et API som tar imot fakturaer og et som tar imot fotografier, å lagre filene på samme sted.

Hva som skjer når API-et kalles med en fil:

1. Filen lagres i den valgte lagringen.
2. I pipelinen slutter argumentet å være filen i rå form og blir en referanse med filename, mimeType, size og et token — det er dette et Skript-trinn får i input["args"]["navnetPåArg"].
3. Appen sitter igjen med registreringen av filen, som enhver annen fil sendt inn av brukerne.

For å teste blir testverdi-kolonnen til en filvelger — velg en fra din egen datamaskin og trykk på Kjør.

Utenfra sendes filen som en multipart-variabel i GraphQL-forespørselen (standardformatet for GraphQL-opplasting); inne på plattformen ordner skjermene det for deg.

#Pipelinen

Seksjonen Pipeline er der API-et får kropp. Reglene er enkle:

• Trinnene kjører i rekkefølge; resultatet av det siste er svaret fra API-et.
• Hvert trinn (fra og med det andre) kan motta resultatet fra det forrige — merket «mottar resultatet fra trinn N» minner om det.
• I SQL- og HTTP-trinnene ligger det forrige resultatet i :prev, og det godtar stier: :prev.id, :prev.0.id.
• Du legger til trinn med knappene SQL-spørring, HTTP-kall og Skript; knappen Tabell konverterer API-et til tabellnaturen (og kan ikke kombineres med de øvrige blokkene).

Så lenge det ikke finnes blokker, foreslår seksjonen veien: standarden er en Tabell fra modellen; alternativt bygges en pipeline med trinnene som beskrives nedenfor.

#Trinnet SQL-spørring

1. Velg Datakilde — en av databasene som er registrert i appen. Uten datakilder viser trinnet snarveien for å opprette den første.
2. Skriv spørringen i editoren. Skriv : for å autofullføre argumenter; editoren kjenner tabellene og kolonnene i den valgte datakilden og foreslår dem mens du skriver.
3. Hvis spørringen av natur returnerer én enkelt rad (en total, en post per nøkkel), slå på Returner bare første rad — svaret går fra liste til objekt.

Verdiene til :argument og :prev sendes alltid som parametere til databasen — aldri sammensatt i spørreteksten. Det beskytter deg mot SQL-injeksjon uten noe strev.

#Trinnet HTTP-kall

For å snakke med eksterne tjenester:

1. Velg Metode (GET, POST, PUT, PATCH eller DELETE) og fyll inn URL — f.eks. https://api.exemplo.pt/clientes/:clienteId.
2. Legg til Headere med Legg til header — for eksempel Authorization med verdien Bearer :token.
3. I metodene med kropp, fyll inn Body; slå på Send som JSON for at kroppen skal sendes med riktig innholdstype.

:navnetPåArg og :prev erstattes i URL-en, headerne og body.

#Trinnet Skript

Skript-trinnet kjører et skript i appen — den samme logikken som du kan kjøre for hånd eller etter tidsplan, nå som del av et API:

1. Velg Skript i listen (listen viser navnet og språket til hvert av dem; bare aktive skript vises). Uten skript viser trinnet snarveien for å opprette det første.
2. Bestem om trinnet Mottar resultatet fra forrige trinn — på det første trinnet i pipelinen gjelder ikke denne bryteren.

Kontrakten med skriptet er tydelig: argumentene til API-et kommer i input["args"], resultatet fra det forrige trinnet i input["prev"], og verdien som returneres av funksjonen main(input) går videre til neste trinn (eller er svaret, hvis det er det siste trinnet).

#Omorganisere og fjerne trinn

Hvert trinnkort har piler for Flytt opp / Flytt ned og en søppelkasse for Fjern trinn. Å endre pipelinen ugyldiggjør resultatet av den siste testen — trykk på Kjør igjen for å se ferske resultater.

#Teste uten å lagre

Fanen Test har to verktøy. Det første, Test pipelinen (utkast), kjører pipelinen SLIK DEN ER i builderen, uten å lagre:

1. Fyll inn testverdiene for argumentene (i seksjonen Argumenter).
2. Trykk på Kjør. I en mutation ber builderen om bekreftelse — «Kjøre mutation nå?» — fordi testen kjører på ordentlig mot datakildene, og en mutation gjør ekte skrivinger.
3. Les resultatet: merket Vellykket/Feil med varigheten, det komplette Svar-et (svært store svar vises avkortet), og med mer enn ett trinn, Resultat per trinn — hvert trinn med merket ok/feil, så du ser nøyaktig hvor pipelinen knakk.
4. Hvis trinnene skrev logger (et skript som printer, for eksempel), dukker de opp i blokken Logger.

#Returtypen

Returtypen er formen på svaret i GraphQL-skjemaet — det er den som forteller klientene hvilke felt de kan velge. Builderen utleder den fra det faktiske resultatet: etter hver kjøring, se blokken Returtype (utledet). Hvis den avviker fra det som er lagret, dukker varselet «Denne returtypen er ikke lagret ennå» opp med knappen Lagre returtype — og en ravgul prikk på knappen Lagre minner om det samme.

#Prøve som en klient

Det andre verktøyet på fanen Test er et interaktivt GraphQL-miljø rettet mot appens endepunkt — du skriver operasjoner, har autofullføring av skjemaet og ser svarene. Siden du er autentisert, vises også utkastene. Knappen Åpne i vindu åpner det samme miljøet i en nettleserfane. Detaljene står i neste kapittel, i GraphQL-API-et for modellen.

#Publisere

Bryteren Publisert styrer hvem som ser API-et:

• Utkast — bare den som bygger, ser det (i autentiserte økter vises operasjonene merket som utkast). Eksterne klienter og brukere av appen ser det ikke, ikke engang ved opplisting av skjemaet.
• Publisert — går inn i skjemaet for alle klienter med tilgang.

For å lagre som publisert må API-et være komplett. Builderen viser blokkeringene ved toppteksten — for eksempel «Trinn 2: SQL-en er tom.» eller, i et tabell-API, «For å lagre som publisert må du velge tabellen og minst én CRUD-handling.» Disse varslene hindrer aldri Lagre som utkast: de hindrer bare publiseringen.

#Den genererte dokumentasjonen (fanen Dokumentasjon)

Fanen Dokumentasjon svarer på spørsmålet «hvordan kaller jeg dette utenfra?». Den genereres fra den lagrede versjonen — lagre API-et først — og viser:

• Endepunktet (POST /api/graphql/gestao-clientes), med kopieringsknapp.
• Merknaden om autentisering: headeren x-api-key er påkrevd for eksterne klienter — nøklene genereres under API-nøkler. I fanen Test (intern økt) trengs den ikke.
• Én oppføring per operasjon i API-et med fire blokker klare til å kopieres: GraphQL-spørring, Variabler, curl og JavaScript (fetch). I et tabell-API vises alle de aktive operasjonene (get, count, add, update, delete).

#Hvorfor kan jeg ikke…?

• Hvorfor får jeg ikke publisert? Pipelinen mangler å være komplett — les blokkeringene ved toppteksten: hvert trinn som mangler, listes opp med nummer og årsak.
• Hvorfor ber Kjør meg om bekreftelse? API-et er en mutation: testen gjør ekte skrivinger. Forsikre deg om at du peker mot testdata.
• Hvorfor ser jeg ikke det nye API-et mitt i GraphQL-testmiljøet? Lagre først — miljøet svarer over den lagrede versjonen. Lagrede utkast vises (du er autentisert); for eksterne klienter, først når du publiserer.
• Hvorfor kan jeg ikke legge et SQL-trinn til et Tabell-API? Et Tabell-API kan ikke kombineres med andre blokker — fjern Tabell-blokken først (eller trinnene, i motsatt retning).