API-rakennin

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), 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.

#API:n luominen

1. Paina paneelissa Koodi, rivillä API:t, painiketta + (Uusi API). Yhteenvetosivun painike Uusi API vie samaan paikkaan: sovelluksen työtilaan.
2. Anna Nimi. Nimi on GraphQL-kenttä, jota asiakkaat kutsuvat, joten noudata sääntöä: kirjaimia, numeroita ja alaviiva, ei numerolla alkava — esimerkiksi getOportunidadesPorConta.
3. Paina Luo API. API syntyy luonnoksena ja rakennin avautuu heti — siellä päätät luonteen (SQL-, HTTP-, skripti- tai taululohkot).

#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.

#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:

1. Tiedosto tallennetaan valittuun tallennustilaan.
2. Pipelinessä argumentti lakkaa olemasta raaka tiedosto ja muuttuu viitteeksi, jolla on filename, mimeType, size ja token — tämän Skripti-vaihe saa kohteessa input["args"]["argumentinNimi"].
3. 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.

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 ja Skripti; 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

1. Valitse Tietolähde — yksi sovellukseen rekisteröidyistä tietokannoista. Ilman tietolähteitä vaihe näyttää oikotien ensimmäisen luomiseen.
2. Kirjoita kysely editoriin. Kirjoita : täydentääksesi argumentteja; editori tuntee valitun tietolähteen taulut ja sarakkeet ja ehdottaa niitä kirjoittaessasi.
3. 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.

#Vaihe HTTP-kutsu

Ulkoisten palveluiden kanssa puhumiseen:

1. Valitse Metodi (GET, POST, PUT, PATCH tai DELETE) ja täytä URL — esim. https://api.exemplo.pt/clientes/:clienteId.
2. Lisää Otsakkeet painikkeella Lisää otsake — esimerkiksi Authorization arvolla Bearer :token.
3. 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.

#Vaihe Skripti

Skripti-vaihe suorittaa sovelluksen skriptin — saman logiikan, jonka voit ajaa käsin tai ajastettuna, nyt osana API:a:

1. 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.
2. 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).

#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:

1. Täytä argumenttien testiarvot (Argumentit-osiossa).
2. Paina Suorita. Mutationissa rakennin pyytää vahvistuksen — ”Suoritetaanko mutation nyt?” — koska testi suoritetaan oikeasti tietolähteitä vasten ja mutation tekee todellisia kirjoituksia.
3. 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.
4. 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.

#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.

#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-key on 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ä).