De API-builder

Elke API van Keplin is een GraphQL-bewerking van de app: een query die gegevens leest of een mutation die ze schrijft. De schermen van de app zelf, de rapporten, de workflows en de externe systemen roepen allemaal dezelfde API's aan — wat u hier bepaalt is de enige weg waarlangs gegevens de applicatie in en uit gaan.

Een API kan een van twee naturen hebben:

Natuur	Wat het is	Waar het verder gaat
Pipeline	Een reeks stappen (SQL-query, HTTP-aanroep, Script) die op volgorde draait; het resultaat van de laatste stap is het antwoord.	Deze pagina
Tabel	Eén enkel blok gekoppeld aan een tabel van het gegevensmodel, dat de lees- en schrijfbewerkingen (get/add/update/delete) voor u genereert.	De GraphQL-API van het model

Deze pagina behandelt de builder zelf: de API aanmaken, argumenten bepalen, de pipeline samenstellen, testen zonder op te slaan en publiceren.

#Waar de API's leven

Open binnen een app het paneel Code in de zijbalk. De sectie API's somt de bestaande API's op — u kunt ze in mappen ordenen met Nieuwe map — en elke API opent als tabblad van de werkruimte. De app heeft ook een overzichtspagina met de volledige lijst, het type en de status van elke API, en het adres waar ze geserveerd worden.

#Een API aanmaken

1. Klik in het paneel Code, op de regel API's, op de knop + (Nieuwe API). De knop Nieuwe API van de overzichtspagina brengt u naar dezelfde plek: de werkruimte van de app.
2. Geef een Naam. De naam is het GraphQL-veld dat de clients gaan aanroepen, dus volgt hij de regel: letters, cijfers en underscores, niet beginnend met een cijfer — bijvoorbeeld getOportunidadesPorConta.
3. Klik op API aanmaken. De API ontstaat als concept en de builder opent daarna — daar beslist u de natuur (blokken SQL, HTTP, script of tabel).

#De builder in één oogopslag

De kop van de builder toont de naam, een badge met het type (query, mutation of tabel) en de status (gepubliceerd of concept). Rechts staan de opdrachten die voor de hele API gelden:

Opdracht	Wat die doet
Gepubliceerd	Zet de publicatie aan/uit. Een API in concept is alleen zichtbaar voor wie bouwt; externe clients zien haar niet.
Openbaar (zonder sessie)	Maakt de API toegankelijk zonder sessie of API-sleutel — voor openbare schermen van de app. Zie Openbare API's.
Opslaan	Slaat de API op zoals zij is. Opslaan kan altijd met een geldige naam en geldige argumenten — half werk slaat u gewoon op.

Daaronder is het werk verdeeld over drie tabbladen:

Tabblad	Waarvoor
Bouwen	Identificatie, argumenten en de pipeline van stappen.
Testen	De pipeline in concept uitvoeren en de API uitproberen als een client.
Docs	Kant-en-klare voorbeelden om te kopiëren, om de API van buitenaf aan te roepen.

#Identificatie

In de sectie Identificatie bepaalt u:

• Bewerking — Query — leest gegevens of Mutation — schrijft gegevens. De keuze is semantisch en praktisch: de mutations vragen om bevestiging vóór elke testuitvoering, omdat zij echt schrijven.
• Naam — het GraphQL-veld. Is de naam ongeldig, dan waarschuwt de builder: "Eenvoudige camelCase: letters, cijfers en underscores, niet beginnend met een cijfer."

In een API van het type Tabel is er geen keuze van bewerking — de bewerkingen volgen uit de CRUD-acties die u in het blok Tabel inschakelt.

#Argumenten

De sectie Argumenten declareert de parameters die de clients aan de API meegeven. Elk argument heeft:

Kolom	Wat het is
Naam	Identificatie van het argument (letters, cijfers, underscores; niet beginnend met een cijfer).
Type	Een van: String, Int, Float, Boolean, ID, JSON, Upload.
Verpl.	Of de client verplicht is het argument mee te sturen.
Standaard	Waarde die gebruikt wordt wanneer de client niets meestuurt.
Testwaarde	Alleen voor de knop Uitvoeren van het tabblad Testen — heeft geen invloed op de clients.

Binnen de pipeline zijn de argumenten beschikbaar als :naam in de stappen SQL en HTTP, en als input["args"]["naam"] in de stap Script.

#Bestanden als argument (type Upload)

Een argument van het type Upload ontvangt een bestand. In dat geval maakt de kolom Standaard plaats voor de keuze van de opslag: Van de app gebruikt de standaardopslag; als alternatief kiest u een van de opslagplaatsen die in de instellingen van de app zijn ingesteld (sectie Opslag). Zo hoeven een API die facturen ontvangt en een API die foto's ontvangt de bestanden niet op dezelfde plek te bewaren.

Wat er gebeurt wanneer de API met een bestand wordt aangeroepen:

1. Het bestand wordt in de gekozen opslag bewaard.
2. In de pipeline is het argument niet langer het ruwe bestand maar een verwijzing met filename, mimeType, size en een token — dat is wat een stap Script ontvangt in input["args"]["naamVanHetArg"].
3. De app houdt de registratie van het bestand bij, zoals bij elk ander bestand dat gebruikers versturen.

Om te testen verandert de kolom met de testwaarde in een bestandskiezer — kies er een van uw computer en klik op Uitvoeren.

Van buitenaf stuurt u het bestand als multipart-variabele van het GraphQL-verzoek (het standaardformaat voor GraphQL-uploads); binnen het platform regelen de schermen dat voor u.

#De pipeline

De sectie Pipeline is waar de API vorm krijgt. De regels zijn eenvoudig:

• De stappen lopen op volgorde; het resultaat van de laatste is het antwoord van de API.
• Elke stap (vanaf de tweede) mag het resultaat van de vorige ontvangen — de badge "ontvangt het resultaat van stap N" herinnert eraan.
• In de stappen SQL en HTTP staat het vorige resultaat in :prev, en dat accepteert paden: :prev.id, :prev.0.id.
• U voegt stappen toe met de knoppen SQL-query, HTTP-aanroep en Script; de knop Tabel zet de API om naar de tabelnatuur (en combineert niet met de overige blokken).

Zolang er geen blokken zijn, stelt de sectie de weg voor: de standaard is een Tabel uit het model; als alternatief bouwt u een pipeline met de stappen die hierna beschreven worden.

#Stap SQL-query

1. Kies de Datasource — een van de databases die in de app geregistreerd zijn. Zonder datasources toont de stap de snelkoppeling om de eerste aan te maken.
2. Schrijf de query in de editor. Typ : om argumenten aan te vullen; de editor kent de tabellen en kolommen van de gekozen datasource en stelt ze voor terwijl u typt.
3. Geeft de query van nature één enkele rij terug (een totaal, één record per sleutel), schakel dan Alleen de eerste rij teruggeven in — het antwoord gaat van lijst naar object.

De waarden van :argument en :prev gaan altijd geparameteriseerd naar de database — nooit aaneengeschakeld in de tekst van de query. Dat beschermt u zonder enige moeite tegen SQL-injectie.

#Stap HTTP-aanroep

Om met externe diensten te praten:

1. Kies de Methode (GET, POST, PUT, PATCH of DELETE) en vul de URL in — bijv.: https://api.voorbeeld.nl/klanten/:clienteId.
2. Voeg Headers toe met Header toevoegen — bijvoorbeeld Authorization met de waarde Bearer :token.
3. Vul bij de methoden met een body de Body in; schakel Als JSON versturen in zodat de body met het juiste inhoudstype meegaat.

:naamVanHetArg en :prev worden vervangen in de URL, de headers en de body.

#Stap Script

De stap Script voert een script van de app uit — dezelfde logica die u met de hand of volgens planning kunt draaien, nu als onderdeel van een API:

1. Kies het Script in de lijst (de lijst toont van elk de naam en de taal; alleen actieve scripts verschijnen). Zonder scripts toont de stap de snelkoppeling om het eerste aan te maken.
2. Beslis of de stap het Ontvangt het resultaat van de vorige stap — bij de eerste stap van de pipeline geldt deze schakelaar niet.

Het contract met het script is helder: de argumenten van de API komen aan in input["args"], het resultaat van de vorige stap in input["prev"], en de waarde die de functie main(input) teruggeeft, gaat door naar de volgende stap (of is het antwoord, als het de laatste stap is).

#Stappen herschikken en verwijderen

Elke stapkaart heeft pijlen voor Omhoog verplaatsen / Omlaag verplaatsen en een prullenbak voor Stap verwijderen. De pipeline wijzigen maakt het resultaat van de laatste test ongeldig — klik opnieuw op Uitvoeren om verse resultaten te zien.

#Testen zonder op te slaan

Het tabblad Testen heeft twee gereedschappen. Het eerste, De pipeline testen (concept), voert de pipeline uit ZOALS DIE IN de builder staat, zonder op te slaan:

1. Vul de testwaarden van de argumenten in (in de sectie Argumenten).
2. Klik op Uitvoeren. Bij een mutation vraagt de builder om bevestiging — "De mutation nu uitvoeren?" — omdat de test echt tegen de datasources draait en een mutation echte schrijfbewerkingen doet.
3. Lees het resultaat: de badge Gelukt/Fout met de duur, het volledige Antwoord (heel grote antwoorden verschijnen afgekapt), en bij meer dan één stap het Resultaat per stap — elke stap met de badge ok/fout, zodat u precies ziet waar de pipeline brak.
4. Hebben de stappen logs weggeschreven (een script dat afdrukt, bijvoorbeeld), dan verschijnen die in het blok Logs.

#Het return type

Het return type is de vorm van het antwoord in het GraphQL-schema — het is wat de clients vertelt welke velden zij mogen selecteren. De builder leidt het af uit het echte resultaat: na elke uitvoering ziet u het blok Return type (afgeleid). Wijkt het af van wat er opgeslagen is, dan verschijnt de melding "Dit return type is nog niet opgeslagen" met de knop Return type opslaan — en een amberkleurige stip op de knop Opslaan herinnert u aan hetzelfde.

#Uitproberen als een client

Het tweede gereedschap van het tabblad Testen is een interactieve GraphQL-omgeving gericht op het endpoint van de app — u schrijft bewerkingen, hebt automatisch aanvullen uit het schema en ziet de antwoorden. Omdat u aangemeld bent, verschijnen ook de concepten. De knop In venster openen opent dezelfde omgeving in een tabblad van de browser. De details staan in het volgende hoofdstuk, in De GraphQL-API van het model.

#Publiceren

De schakelaar Gepubliceerd bepaalt wie de API ziet:

• Concept — alleen wie bouwt ziet haar (in aangemelde sessies verschijnen de bewerkingen als concept gemarkeerd). Externe clients en gebruikers van de app zien haar niet, ook niet in de opsomming van het schema.
• Gepubliceerd — komt in het schema voor alle clients met toegang.

Om als gepubliceerd op te slaan moet de API compleet zijn. De builder toont de blokkades naast de kop — bijvoorbeeld "Stap 2: de SQL is leeg." of, bij een tabel-API, "Om als gepubliceerd op te slaan kiest u de tabel en ten minste één CRUD-actie." Deze meldingen verhinderen nooit het Opslaan in concept: zij verhinderen alleen het publiceren.

#De gegenereerde documentatie (tabblad Docs)

Het tabblad Docs beantwoordt de vraag "hoe roep ik dit van buitenaf aan?". Het wordt gegenereerd uit de opgeslagen versie — sla de API eerst op — en toont:

• Het endpoint (POST /api/graphql/gestao-clientes), met een kopieerknop.
• De notitie over authenticatie: de header x-api-key is verplicht voor externe clients — de sleutels genereert u bij API-sleutels. Op het tabblad Testen (interne sessie) is hij niet nodig.
• Eén ingang per bewerking van de API met vier kant-en-klare blokken om te kopiëren: GraphQL-query, Variables, curl en JavaScript (fetch). Bij een tabel-API verschijnen alle actieve bewerkingen (get, count, add, update, delete).

#Waarom niet…?

• Waarom lukt het publiceren niet? De pipeline is nog niet compleet — lees de blokkades naast de kop: elke ontbrekende stap staat er met het nummer en de reden.
• Waarom vraagt Uitvoeren mij om bevestiging? De API is een mutation: de test doet echte schrijfbewerkingen. Controleer of u naar testgegevens wijst.
• Waarom zie ik mijn nieuwe API niet in de GraphQL-testomgeving? Sla eerst op — de omgeving antwoordt over de opgeslagen versie. Opgeslagen concepten verschijnen wel (u bent aangemeld); voor externe clients pas wanneer u publiceert.
• Waarom mag ik geen SQL-stap aan een Tabel-API toevoegen? Een Tabel-API combineert niet met andere blokken — verwijder eerst het blok Tabel (of de stappen, andersom).