API-byggaren

Varje API i Keplin är en GraphQL-operation i appen: en query som läser data eller en mutation som skriver dem. Appens egna skärmar, rapporterna, arbetsflödena och externa system anropar alla samma API:er — det du definierar här är applikationens enda in- och utgång för data.

Ett API kan ha en av två naturer:

Natur	Vad det är	Var det fördjupas
Pipeline	En sekvens av steg (SQL-fråga, HTTP-anrop, Skript) som körs i ordning; det sista stegets resultat är svaret.	Den här sidan
Tabell	Ett enda block bundet till en tabell i datamodellen, som genererar läs- och skrivoperationerna (get/add/update/delete) åt dig.	Modellens GraphQL-API

Den här sidan täcker byggaren i sig: skapa API:et, definiera argument, bygga pipelinen, testa utan att spara och publicera.

#Var API:erna bor

Inuti en app: öppna panelen Kod i sidofältet. Avsnittet API:er listar de befintliga API:erna — du kan organisera dem i mappar med Ny mapp — och var och en öppnas som en flik i arbetsytan. Appen har också en översiktssida med den fullständiga listan, varje API:s typ och status, och adressen där de serveras.

#Skapa ett API

1. Tryck på knappen + (Nytt API) på raden API:er i panelen Kod. Knappen Nytt API på översiktssidan tar dig till samma ställe: appens arbetsyta.
2. Ge det ett Namn. Namnet är GraphQL-fältet som klienterna kommer att anropa, så följ regeln: bokstäver, siffror och understreck, får inte börja med en siffra — till exempel getOportunidadesPorConta.
3. Tryck på Skapa API. API:et föds som utkast och byggaren öppnas sedan — det är där du bestämmer naturen (SQL-, HTTP-, skript- eller tabellblock).

#Byggaren i korthet

Byggarens rubrik visar namnet, ett märke med typen (query, mutation eller tabell) och statusen (Publicerat eller utkast). Till höger ligger kommandona som gäller hela API:et:

Kommando	Vad det gör
Publicerat	Slår publiceringen på och av. Ett API som är utkast syns bara för den som bygger; externa klienter ser det inte.
Publikt (utan session)	Gör API:et åtkomligt utan session och utan API-nyckel — för appens publika skärmar. Se Publika API:er.
Spara	Sparar API:et som det är. Det går alltid att spara med ett giltigt namn och giltiga argument — halvfärdigt arbete sparas ändå.

Nedanför delas arbetet i tre flikar:

Flik	Till vad
Bygg	Identifikation, argument och stegpipelinen.
Testa	Köra pipelinen som utkast och prova API:et som en klient.
Dokumentation	Färdiga exempel att kopiera för att anropa API:et utifrån.

#Identifikation

I avsnittet Identifikation anger du:

• Operation — Query — läser data eller Mutation — skriver data. Valet är både semantiskt och praktiskt: mutationer ber om bekräftelse före varje testkörning, eftersom de skriver på riktigt.
• Namn — GraphQL-fältet. Om namnet är ogiltigt varnar byggaren: ”Enkel camelCase: bokstäver, siffror och understreck, får inte börja med en siffra.”

I ett Tabell-API finns inget val av operation — operationerna härleds från de CRUD-åtgärder du aktiverar i Tabell-blocket.

#Argument

Avsnittet Argument deklarerar parametrarna som klienterna skickar till API:et. Varje argument har:

Kolumn	Vad det är
Namn	Argumentets identifierare (bokstäver, siffror, understreck; börjar inte med en siffra).
Typ	En av: String, Int, Float, Boolean, ID, JSON, Upload.
Oblig.	Om klienten är tvungen att skicka argumentet.
Standard	Värdet som används när klienten inte skickar något.
Testvärde	Bara för knappen Kör i fliken Testa — det påverkar inte klienterna.

Inuti pipelinen är argumenten tillgängliga som :namn i SQL- och HTTP-stegen, och som input["args"]["namn"] i Skript-steget.

#Filer som argument (typen Upload)

Ett argument av typen Upload tar emot en fil. Då ersätts kolumnen Standard av valet av lagring: Appens standard använder standardlagringen; som alternativ väljer du en av de lagringar som är konfigurerade i appens inställningar (avsnittet Lagring). Så behöver ett API som tar emot fakturor och ett annat som tar emot fotografier inte spara filerna på samma ställe.

Det här händer när API:et anropas med en fil:

1. Filen sparas i den valda lagringen.
2. I pipelinen är argumentet inte längre den råa filen utan en referens med filename, mimeType, size och en token — det är detta ett Skript-steg tar emot i input["args"]["nomeDoArg"].
3. Appen behåller registreringen av filen, som vilken annan fil som helst som användarna skickat in.

För att testa förvandlas testvärdeskolumnen till en filväljare — välj en fil från din dator och tryck på Kör.

Utifrån skickas filen som en multipart-variabel i GraphQL-begäran (standardformatet för GraphQL-uppladdning); inuti plattformen sköter skärmarna det åt dig.

#Pipelinen

Avsnittet Pipeline är där API:et får en kropp. Reglerna är enkla:

• Stegen körs i ordning; det sistas resultat är API:ets svar.
• Varje steg (från och med det andra) kan ta emot föregående stegs resultat — märket ”tar emot resultatet från steg N” påminner om det.
• I SQL- och HTTP-stegen finns föregående resultat i :prev, och det godtar sökvägar: :prev.id, :prev.0.id.
• Du lägger till steg med knapparna SQL-fråga, HTTP-anrop och Skript; knappen Tabell förvandlar API:et till tabellnaturen (och den kombineras inte med de övriga blocken).

Så länge det inte finns några block föreslår avsnittet vägen: standard är en Tabell från modellen; som alternativ bygger man en pipeline med stegen som beskrivs härnäst.

#Steget SQL-fråga

1. Välj Datakälla — en av databaserna som registrerats i appen. Utan datakällor visar steget genvägen för att skapa den första.
2. Skriv frågan i editorn. Skriv : för att autokomplettera argument; editorn känner till den valda datakällans tabeller och kolumner och föreslår dem medan du skriver.
3. Om frågan av sin natur returnerar en enda rad (en summa, en post per nyckel), slå på Returnera bara första raden — svaret går då från lista till objekt.

Värdena i :argument och :prev går alltid parametriserade till databasen — aldrig sammanfogade i frågans text. Det skyddar dig mot SQL-injektion utan någon ansträngning alls.

#Steget HTTP-anrop

För att tala med externa tjänster:

1. Välj Metod (GET, POST, PUT, PATCH eller DELETE) och fyll i URL — t.ex. https://api.exempel.se/kunder/:kundId.
2. Lägg till Headers med Lägg till header — till exempel Authorization med värdet Bearer :token.
3. I metoderna med kropp fyller du i Body; slå på Skicka som JSON för att kroppen ska skickas med rätt innehållstyp.

:nomeDoArg och :prev ersätts i URL, headers och body.

#Steget Skript

Skript-steget kör ett av appens skript — samma logik som du kan köra för hand eller schemalagt, nu som en del av ett API:

1. Välj Skript i listan (listan visar varje skripts namn och språk; bara aktiva skript dyker upp). Utan skript visar steget genvägen för att skapa det första.
2. Bestäm om steget Tar emot resultatet från föregående steg — i pipelinens första steg gäller det reglaget inte.

Avtalet med skriptet är tydligt: API:ets argument kommer in i input["args"], föregående stegs resultat i input["prev"], och värdet som funktionen main(input) returnerar går vidare till nästa steg (eller är svaret, om det är sista steget).

#Ändra ordning på och ta bort steg

Varje stegkort har pilar för Flytta upp / Flytta ned och en papperskorg för Ta bort steg. Att ändra pipelinen ogiltigförklarar det senaste testresultatet — tryck Kör igen för att se färska resultat.

#Testa utan att spara

Fliken Testa har två verktyg. Det första, Testa pipelinen (utkast), kör pipelinen SOM DEN ÄR i byggaren, utan att spara:

1. Fyll i argumentens testvärden (i avsnittet Argument).
2. Tryck på Kör. I en mutation ber byggaren om bekräftelse — ”Kör mutationen nu?” — eftersom testet körs på riktigt mot datakällorna och en mutation gör verkliga skrivningar.
3. Läs resultatet: märket Lyckades/Fel med varaktigheten, det fullständiga Svaret (mycket stora svar visas trunkerade), och med mer än ett steg, Resultat per steg — varje steg med märket ok/fel, så att du ser exakt var pipelinen gick sönder.
4. Om stegen skrev loggar (ett skript som skriver ut, till exempel) dyker de upp i blocket Loggar.

#Returtypen

Returtypen är svarets form i GraphQL-schemat — det är den som säger klienterna vilka fält de kan välja. Byggaren härleder den från det verkliga resultatet: efter varje körning ser du blocket Returtyp (härledd). Om den skiljer sig från den sparade dyker varningen ”Den här returtypen är inte sparad ännu” upp med knappen Spara returtyp — och en bärnstensfärgad punkt på knappen Spara påminner om samma sak.

#Prova som en klient

Fliken Testas andra verktyg är en interaktiv GraphQL-miljö riktad mot appens endpoint — du skriver operationer, får autokomplettering från schemat och ser svaren. Eftersom du är inloggad dyker även utkasten upp. Knappen Öppna i fönster öppnar samma miljö i en webbläsarflik. Detaljerna finns i nästa kapitel, i Modellens GraphQL-API.

#Publicera

Reglaget Publicerat styr vem som ser API:et:

• Utkast — bara den som bygger ser det (i autentiserade sessioner visas operationerna märkta som utkast). Externa klienter och appens användare ser det inte, inte ens genom att lista schemat.
• Publicerat — det kommer in i schemat för alla klienter med åtkomst.

För att spara som publicerat måste API:et vara komplett. Byggaren visar hindren bredvid rubriken — till exempel ”Steg 2: SQL:en är tom.” eller, i ett tabell-API, ”För att spara som publicerat, välj tabell och minst en CRUD-åtgärd.” De varningarna hindrar aldrig Spara som utkast: de hindrar bara publiceringen.

#Den genererade dokumentationen (fliken Dokumentation)

Fliken Dokumentation svarar på frågan ”hur anropar jag det här utifrån?”. Den genereras från den sparade versionen — spara API:et först — och visar:

• Endpointen (POST /api/graphql/gestao-clientes), med en kopieringsknapp.
• Noteringen om autentisering: headern x-api-key är obligatorisk för externa klienter — nycklarna genereras under API-nycklar. I fliken Testa (intern session) behövs den inte.
• En post per operation i API:et med fyra block redo att kopiera: GraphQL-fråga, Variabler, curl och JavaScript (fetch). I ett tabell-API dyker alla aktiva operationer upp (get, count, add, update, delete).

#Varför inte…?

• Varför får jag inte publicera? Pipelinen är inte komplett — läs hindren bredvid rubriken: varje steg som saknar något listas med nummer och orsak.
• Varför ber Kör mig om bekräftelse? API:et är en mutation: testet gör verkliga skrivningar. Kontrollera att du pekar på testdata.
• Varför ser jag inte mitt nya API i GraphQL-testmiljön? Spara först — miljön svarar utifrån den sparade versionen. Sparade utkast dyker upp (du är inloggad); för externa klienter först när du publicerar.
• Varför kan jag inte lägga till ett SQL-steg i ett Tabell-API? Ett Tabell-API kombineras inte med andra block — ta bort Tabell-blocket först (eller stegen, om du går åt andra hållet).