KEPLIN Docs

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.

Koodi-paneeli API:t-osioineen, ja sovelluksen yleiskatsaus endpointin osoitteineen.
Koodi-paneeli API:t-osioineen, ja sovelluksen yleiskatsaus endpointin osoitteineen.

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

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

Modaali Uusi API — vain nimi; luonne määritetään myöhemmin rakentimessa.
Modaali Uusi API — vain nimi; luonne määritetään myöhemmin rakentimessa.

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.

Pipeline-API:n rakennin, välilehdellä Rakenna.
Pipeline-API:n rakennin, välilehdellä Rakenna.

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.

Argumentit-osio, yksi argumentti esiteltynä ja testiarvo täytettynä.
Argumentit-osio, yksi argumentti esiteltynä ja testiarvo täytettynä.

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:

  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.

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

  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.

SQL-kysely-vaihe, tietolähde valittuna ja kyselyn editori.
SQL-kysely-vaihe, tietolähde valittuna ja kyselyn editori.

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:

  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.

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:

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

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.

  1. Valitse Malli: jokin sovelluksen tekstin tekoälymalleista, tai Oletus.
  2. Kirjoita Pyyntö, jossa ovat :nomeDoArg ja :prev. Esimerkiksi: Tiivistä tämä tukipyyntö yhteen lauseeseen: :prev.descricao.
  3. 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.
  4. 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:

  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.

Paneeli Testaa pipeline (luonnos), Suorita-painikkeineen — vielä ilman suorituksia tässä istunnossa.
Paneeli Testaa pipeline (luonnos), Suorita-painikkeineen — vielä ilman suorituksia tässä istunnossa.

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

Docs-välilehti, endpoint ja getContactos-operaation valmiiksi kopioitavat esimerkit.
Docs-välilehti, endpoint ja getContactos-operaation valmiiksi kopioitavat esimerkit.

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