API-rakennin
Sovelluksen API:en luominen vaiheiden pipelineina — SQL, HTTP-kutsut, skriptit ja tekoäly — argumentteineen, sisäänrakennettuine testeineen ja generoituine dokumentaatioineen.
Jokainen Keplinin API on sovelluksen GraphQL-operaatio: query, joka lukee dataa, tai mutation, joka kirjoittaa sitä. Sovelluksen omat näytöt, raportit, työnkulut ja ulkoiset järjestelmät kutsuvat kaikki samoja API:ta — se, mitä täällä määrittelet, on sovelluksen datan ainoa sisään- ja ulosmenoreitti.
API:lla voi olla toinen kahdesta luonteesta:
| Luonne | Mikä se on | Missä syvennytään |
|---|---|---|
| Pipeline | Vaiheiden sarja (SQL-kysely, HTTP-kutsu, Skripti, Tekoäly), joka suoritetaan järjestyksessä; viimeisen vaiheen tulos on vastaus. | Tämä sivu |
| Taulu | Yksi lohko, joka on sidottu datamallin tauluun ja joka generoi luku- ja kirjoitusoperaatiot (get/add/update/delete) puolestasi. | Mallin GraphQL-API |
Tämä sivu kattaa itse rakentimen: API:n luomisen, argumenttien määrittelyn, pipelinen kokoamisen, testaamisen tallentamatta ja julkaisemisen.
Missä API:t asuvat
Avaa sovelluksen sisällä sivupalkin paneeli Koodi. Osio API:t listaa olemassa olevat API:t — voit järjestää ne kansioihin painikkeella Uusi kansio — ja jokainen avautuu työtilan välilehtenä. Sovelluksella on myös yhteenvetosivu, jossa on täydellinen lista, kunkin API:n tyyppi ja tila, sekä osoite, jossa niitä tarjoillaan.

Huomio
Listan yläreunassa näet sovelluksen osoitteen: kaikki operaatiot
tarjoillaan yhdessä GraphQL-endpointissa, tyyliin
/api/graphql/gestao-clientes. URL:ää API:a kohden ei ole — on
GraphQL-kenttä API:a kohden.
API:n luominen
- Paina paneelissa Koodi, rivillä API:t, painiketta + (Uusi API). Yhteenvetosivun painike Uusi API vie samaan paikkaan: sovelluksen työtilaan.
- Anna Nimi. Nimi on GraphQL-kenttä, jota asiakkaat kutsuvat, joten
noudata sääntöä: kirjaimia, numeroita ja alaviiva, ei numerolla
alkava — esimerkiksi
getOportunidadesPorConta. - Paina Luo API. API syntyy luonnoksena ja rakennin avautuu heti — siellä päätät luonteen (SQL-, HTTP-, skripti- tai taululohkot).

Vinkki
Jos API:sta tulee Taulu-API, älä käytä nimessä etuliitteitä kuten
get tai add: nimi on operaatioiden PERUSTA. Taulu-API:sta nimeltä
contas generoituvat getContas, addContas, updateContas ja
deleteContas — sen mukaan, mitkä toiminnot aktivoit.
Rakennin yhdellä silmäyksellä
Rakentimen ylätunniste näyttää nimen, tyyppimerkin (query, mutation
tai taulu) ja tilan (julkaistu tai luonnos). Oikealla ovat
komennot, jotka koskevat koko API:a:
| Komento | Mitä se tekee |
|---|---|
| Julkaistu | Kytkee julkaisun päälle/pois. Luonnostilassa oleva API näkyy vain rakentajille; ulkoiset asiakkaat eivät näe sitä. |
| Julkinen (ilman istuntoa) | Tekee API:sta käytettävän ilman istuntoa ja API-avainta — sovelluksen julkisille näytöille. Katso Julkiset API:t. |
| Tallenna | Tallentaa API:n sellaisenaan. Tallentaminen on aina mahdollista, kun nimi ja argumentit ovat kelvolliset — keskeneräinenkin työ tallentuu. |
Sen alla työ jakautuu kolmeen välilehteen:
| Välilehti | Mihin |
|---|---|
| Rakenna | Tunnistetiedot, argumentit ja vaiheiden pipeline. |
| Testaa | Luonnospipelinen suorittaminen ja API:n kokeileminen asiakkaan tavoin. |
| Docs | Valmiit kopioitavat esimerkit API:n kutsumiseen ulkoa. |

Tunnistetiedot
Osiossa Tunnistetiedot määrität:
- Operaatio — Query — lukee dataa tai Mutation — kirjoittaa dataa. Valinta on semanttinen ja käytännöllinen: mutationit pyytävät vahvistuksen ennen jokaista testisuoritusta, koska ne kirjoittavat oikeasti.
- Nimi — GraphQL-kenttä. Jos nimi on kelvoton, rakennin varoittaa: ”Pelkkä camelCase: kirjaimia, numeroita ja alaviiva, ei numerolla alkava.”
Taulu-API:ssa operaatiota ei valita — operaatiot johdetaan Taulu-lohkossa aktivoimistasi CRUD-toiminnoista.
Argumentit
Osio Argumentit esittelee parametrit, jotka asiakkaat välittävät API:lle. Jokaisella argumentilla on:
| Sarake | Mikä se on |
|---|---|
| Nimi | Argumentin tunniste (kirjaimia, numeroita, alaviiva; ei ala numerolla). |
| Tyyppi | Yksi näistä: String, Int, Float, Boolean, ID, JSON, Upload. |
| Pak. | Onko asiakkaan pakko lähettää argumentti. |
| Oletus | Arvo, jota käytetään kun asiakas ei lähetä mitään. |
| Testiarvo | Vain Testaa-välilehden Suorita-painiketta varten — ei vaikuta asiakkaisiin. |
Pipelinen sisällä argumentit ovat käytettävissä muodossa :nimi
SQL- ja HTTP-vaiheissa, ja muodossa input["args"]["nimi"]
Skripti-vaiheessa.

Vinkki
Kirjoita pipeline ensin, jos niin mieluummin teet: kun käytät
:jokinNimi vaiheessa esittelemättä sitä, näkyviin tulee palkki
”Pipelinessä käytössä mutta vielä määrittelemättä:” ja painike nimeä
kohden — yksi napsautus ja argumentti on luotu.
Tiedostot argumenttina (Upload-tyyppi)
Upload-tyyppinen argumentti vastaanottaa tiedoston. Siinä tapauksessa
Oletus-sarake väistyy tallennustilan valinnan tieltä: Sovelluksen
oletus käyttää oletustallennustilaa; vaihtoehtoisesti valitse yksi
sovelluksen asetuksissa (osio Tallennustila) määritetyistä
tallennustiloista. Näin API, joka vastaanottaa laskuja, ja toinen, joka
vastaanottaa valokuvia, eivät joudu tallentamaan tiedostoja samaan
paikkaan.
Mitä tapahtuu, kun API:a kutsutaan tiedoston kanssa:
- Tiedosto tallennetaan valittuun tallennustilaan.
- Pipelinessä argumentti lakkaa olemasta raaka tiedosto ja muuttuu
viitteeksi, jolla on
filename,mimeType,sizejatoken— tämän Skripti-vaihe saa kohteessainput["args"]["argumentinNimi"]. - Sovellukselle jää merkintä tiedostosta, kuten mistä tahansa muusta käyttäjien lähettämästä tiedostosta.
Testaamista varten testiarvon sarake muuttuu tiedostovalitsimeksi — valitse tiedosto omalta koneeltasi ja paina Suorita.
Varoitus
Jos sovelluksella on useita tallennustiloja eikä yhtäkään ole merkitty
oletukseksi, Upload-kutsu ilman valittua tallennustilaa hylätään —
alusta ei valitse puolestasi.
Ulkoa tiedosto lähetetään GraphQL-pyynnön multipart-muuttujana (GraphQL-latauksen vakiomuoto); alustan sisällä näytöt hoitavat sen puolestasi.
Pipeline
Osio Pipeline on paikka, jossa API saa muotonsa. Säännöt ovat yksinkertaiset:
- Vaiheet suoritetaan järjestyksessä; viimeisen tulos on API:n vastaus.
- Jokainen vaihe (toisesta alkaen) voi saada edellisen tuloksen — merkki ”saa vaiheen N tuloksen” muistuttaa siitä.
- SQL- ja HTTP-vaiheissa edellinen tulos on kohteessa
:prev, ja se hyväksyy polkuja::prev.id,:prev.0.id. - Vaiheita lisätään painikkeilla SQL-kysely, HTTP-kutsu, Skripti ja Tekoäly; painike Taulu muuntaa API:n taululuonteeseen (eikä yhdisty muihin lohkoihin).
Niin kauan kuin lohkoja ei ole, osio ehdottaa polkua: oletus on mallin Taulu; vaihtoehtoisesti kootaan pipeline seuraavaksi kuvatuista vaiheista.
Vaihe SQL-kysely
- Valitse Tietolähde — yksi sovellukseen rekisteröidyistä tietokannoista. Ilman tietolähteitä vaihe näyttää oikotien ensimmäisen luomiseen.
- Kirjoita kysely editoriin. Kirjoita
:täydentääksesi argumentteja; editori tuntee valitun tietolähteen taulut ja sarakkeet ja ehdottaa niitä kirjoittaessasi. - Jos kysely palauttaa luonnostaan yhden rivin (summan, tietueen avaimella), kytke päälle Palauta vain ensimmäinen rivi — vastaus muuttuu listasta objektiksi.
:argumentti- ja :prev-arvot menevät tietokantaan aina
parametreina — niitä ei koskaan yhdistetä kyselyn tekstiin. Se
suojaa sinut SQL-injektiolta ilman mitään vaivaa.

Vinkki
Toisesta vaiheesta alkaen :prev näkyy myös automaattisessa
täydennyksessä — testisuorituksen jälkeen ehdotukset sisältävät
edellisen tuloksen todelliset polut (esim. :prev.0.id). Suurten
listojen muuntamiseen vaiheiden välillä laita koodivaihe väliin.
: on argumentti vain siellä, missä tietokanta lukee sen sellaisena.
Tekstin (':x'), lainausmerkeissä olevan nimen, kommentin tai PostgreSQL:n
tyyppimuunnoksen (arvo::int) sisällä se jää ennalleen.
Vaiheen SQL tallentuu muotoiltuna valitun tietolähteen murteella. Vain
välilyönnit ja rivinvaihdot muuttuvat: sanat säilyttävät kirjainkokonsa, ja
tekstit, kommentit, tyyppimuunnokset ja :nimi-merkit pysyvät ennallaan.
Vaihe HTTP-kutsu
Ulkoisten palveluiden kanssa puhumiseen:
- Valitse Metodi (GET, POST, PUT, PATCH tai DELETE) ja täytä
URL — esim.
https://api.exemplo.pt/clientes/:clienteId. - Lisää Otsakkeet painikkeella Lisää otsake — esimerkiksi
AuthorizationarvollaBearer :token. - Täytä metodeissa, joissa on runko, Runko; kytke päälle Lähetä JSON-muodossa, jotta runko lähtee oikealla sisältötyypillä.
:argumentinNimi ja :prev korvataan URL:ssä, otsakkeissa ja rungossa.
Jokainen arvo kirjoitetaan paikkaansa sopivaksi. URL:ssa se koodataan
(Silva & Filhos saapuu yhtenä arvona). JSON-bodyssa se saa lainausmerkit
ja escape-merkit: {"nome": ":nome"} pysyy kelvollisena, vaikka nimessä
olisi lainausmerkkejä tai rivinvaihtoja, ja lainausmerkkien ulkopuolella
({"id": :id}) teksti saa puuttuvat lainausmerkit. URL:n alussa oleva arvo
(pohja, :base/clientes) menee sellaisenaan.
Pyyntö odottaa vastausta enintään 60 sekuntia; sen jälkeen vaihe
epäonnistuu viestillä "Palvelu … ei vastannut 60 sekunnissa". Vaiheen
määrityksen kenttä timeoutMs muuttaa aikaa, enintään 120 sekuntiin.
Vaihe Skripti
Skripti-vaihe suorittaa sovelluksen skriptin — saman logiikan, jonka voit ajaa käsin tai ajastettuna, nyt osana API:a:
- Valitse Skripti listasta (lista näyttää kunkin nimen ja kielen; vain aktiiviset skriptit näkyvät). Ilman skriptejä vaihe näyttää oikotien ensimmäisen luomiseen.
- Päätä, ottaako vaihe Saa edellisen vaiheen tuloksen — pipelinen ensimmäisessä vaiheessa tämä kytkin ei päde.
Sopimus skriptin kanssa on selvä: API:n argumentit saapuvat kohteessa
input["args"], edellisen vaiheen tulos kohteessa input["prev"], ja
funktion main(input) palauttama arvo jatkaa seuraavaan vaiheeseen
(tai on vastaus, jos kyseessä on viimeinen vaihe).
Varoitus
Jos valitulla skriptillä on korkea aikaraja, rakennin varoittaa — API:n asiakkaat odottavat pahimmillaan sen ajan. Interaktiivisen vastauksen pipelinet ansaitsevat nopeat skriptit.
Vaihe Tekoäly
Tekoäly-vaihe lähettää ilman koodia pyynnön sovelluksen tekoälymallille ja välittää vastauksen seuraavalle vaiheelle, tai palauttaa sen, jos se on viimeinen vaihe.
- Valitse Malli: jokin sovelluksen tekstin tekoälymalleista, tai Oletus.
- Kirjoita Pyyntö, jossa ovat
:nomeDoArgja:prev. Esimerkiksi:Tiivistä tämä tukipyyntö yhteen lauseeseen: :prev.descricao. - Valinnainen: kirjoita Ohjeet (mallin rooli ja säännöt),
Tiedostot (tiedostoja sisältävät merkinnät pilkuilla erotettuina,
kuten Upload-argumentin
:documento) ja Vastauksen JSON Schema. - Valinnainen: kirjoita nimi kohtaan Vastaus reaaliajassa, jotta teksti näkyy API:n kutsujan näytöllä sitä mukaa kuin malli kirjoittaa sitä (ks. Vastaukset reaaliajassa näytöllä).
Ilman JSON Schemaa seuraava vaihe saa vastauksen tekstin; sen kanssa se saa
valmiiksi validoidut tiedot. Pyynnössä ja ohjeissa :nimi, joka ei ole
argumentti eikä prev, jää ennalleen: ”Huom:tärkeä” ei ole merkintä.
Jos tekoälypalvelu epäonnistuu, API vastaa virheellä 502, tai 504, kun aika loppuu. Suorituksen lokit näyttävät kutsun keston ja, kun sovelluksen tekoälymallien Virheenjäljitys on päällä, pyynnön ja vastauksen tekstin.
Vaiheiden järjestäminen ja poistaminen
Jokaisella vaihekortilla on nuolet Siirrä ylös / Siirrä alas ja roskakori Poista vaihe -toiminnolle. Pipelinen muuttaminen mitätöi viimeisen testin tuloksen — paina Suorita uudelleen nähdäksesi tuoreet tulokset.
Testaaminen tallentamatta
Välilehdellä Testaa on kaksi työkalua. Ensimmäinen, Testaa pipeline (luonnos), suorittaa pipelinen SELLAISENA KUIN SE ON rakentimessa, tallentamatta:
- Täytä argumenttien testiarvot (Argumentit-osiossa).
- Paina Suorita. Mutationissa rakennin pyytää vahvistuksen — ”Suoritetaanko mutation nyt?” — koska testi suoritetaan oikeasti tietolähteitä vasten ja mutation tekee todellisia kirjoituksia.
- Lue tulos: merkki Onnistui/Virhe kestoineen, täydellinen
Vastaus (hyvin suuret vastaukset näytetään katkaistuina) ja,
useammalla kuin yhdellä vaiheella, Tulos vaiheittain — jokainen
vaihe merkillä
ok/virhe, jotta näet tarkalleen, missä pipeline hajosi. - Jos vaiheet kirjoittivat lokeja (esimerkiksi tulostava skripti), ne näkyvät lohkossa Lokit.

Return type
Return type on vastauksen muoto GraphQL-schemassa — se kertoo asiakkaille, mitä kenttiä he voivat valita. Rakennin päättelee sen todellisesta tuloksesta: jokaisen suorituksen jälkeen näet lohkon Return type (päätelty). Jos se eroaa tallennetusta, näkyviin tulee varoitus ”Tätä return typea ei ole vielä tallennettu.” painikkeineen Tallenna return type — ja keltainen piste painikkeessa Tallenna muistuttaa samasta.
Huomio
Ilman yhtäkään suoritusta välilehti näyttää kohdan Nykyinen return type (tallennetun). Suorita pipeline päätelläksesi return typen todellisesta tuloksesta — erityisesti sen jälkeen, kun muutat SQL:ää tai skriptiä.
Kokeileminen asiakkaan tavoin
Testaa-välilehden toinen työkalu on interaktiivinen GraphQL-ympäristö, joka osoittaa sovelluksen endpointiin — kirjoitat operaatioita, saat scheman automaattisen täydennyksen ja näet vastaukset. Koska olet kirjautunut, myös luonnokset näkyvät. Painike Avaa ikkunassa avaa saman ympäristön selaimen välilehteen. Yksityiskohdat ovat seuraavassa luvussa, kohdassa Mallin GraphQL-API.
Julkaiseminen
Kytkin Julkaistu ohjaa sitä, kuka näkee API:n:
- Luonnos — vain rakentajat näkevät sen (kirjautuneissa istunnoissa operaatiot näkyvät luonnokseksi merkittyinä). Ulkoiset asiakkaat ja sovelluksen käyttäjät eivät näe sitä, eivät edes scheman listauksessa.
- Julkaistu — tulee schemaan kaikille asiakkaille, joilla on pääsy.
Julkaistuna tallentamista varten API:n on oltava valmis. Rakennin näyttää esteet ylätunnisteen vieressä — esimerkiksi ”Vaihe 2: SQL on tyhjä.” tai, taulu-API:ssa, ”Jotta voit tallentaa julkaistuna, valitse taulu ja vähintään yksi CRUD-toiminto.” Nämä varoitukset eivät koskaan estä Tallenna-painiketta luonnostilassa: ne estävät vain julkaisun.
Huomio
Julkaistun API:n poistaminen ottaa operaation heti pois schemasta — sitä kutsuneet asiakkaat alkavat saada virheen. Alusta varoittaa etukäteen: poisto on pysyvä.
Generoitu dokumentaatio (Docs-välilehti)
Välilehti Docs vastaa kysymykseen ”miten kutsun tätä ulkoa?”. Se generoidaan tallennetusta versiosta — tallenna API ensin — ja näyttää:
- Endpointin (
POST /api/graphql/gestao-clientes), kopiointipainikkeella. - Tunnistautumishuomautuksen: otsake
x-api-keyon pakollinen ulkoisille asiakkaille — avaimet luodaan kohdassa API-avaimet. Testaa-välilehdellä (sisäinen istunto) sitä ei tarvita. - Merkinnän API:n jokaista operaatiota kohden, neljällä valmiiksi kopioitavalla lohkolla: GraphQL-kysely, Muuttujat, curl ja JavaScript (fetch). Taulu-API:ssa näkyvät kaikki aktiiviset operaatiot (get, count, add, update, delete).

Miksi ei…?
- Miksi en saa julkaistua? Pipeline ei ole valmis — lue esteet ylätunnisteen vierestä: jokainen puuttuva vaihe listataan numeroineen ja syineen.
- Miksi Suorita pyytää vahvistusta? API on mutation: testi tekee todellisia kirjoituksia. Varmista, että osoitat testidataan.
- Miksi en näe uutta API:ani GraphQL-testiympäristössä? Tallenna ensin — ympäristö vastaa tallennetusta versiosta. Tallennetut luonnokset näkyvät (olet kirjautunut); ulkoisille asiakkaille vasta kun julkaiset.
- Miksi en voi lisätä SQL-vaihetta Taulu-API:in? Taulu-API ei yhdisty muihin lohkoihin — poista Taulu-lohko ensin (tai vaiheet, toiseen suuntaan mentäessä).