Mallin GraphQL-API

Jokainen Keplin-sovellus tarjoilee GraphQL-API:n omassa endpointissaan. Sen API:n schemaa ei kirjoiteta käsin: se generoidaan kahdesta lähteestä — rakentimessa rakentamistasi API:sta ja sovelluksen datamallista. Mallin tauluista tulee GraphQL-tyyppejä kenttineen ja suhteineen; mallin enumeista tulee GraphQL-enumeja; ja Taulu-API muuntaa taulun täydellisiksi luku- ja kirjoitusoperaatioiksi, suodattimineen, järjestämisineen ja sivutuksineen, ilman että kirjoitat riviäkään SQL:ää.

Tämä sivu kattaa endpointin, Taulu-API:t ja kyselykielen, jonka ne tarjoavat asiakkaille.

#Sovelluksen endpoint

Kaikki sovelluksen operaatiot tarjoillaan yhdessä GraphQL-endpointissa:

POST /api/graphql/<sovelluksen-osoite>

Esimerkkisovelluksessa POST /api/graphql/gestao-clientes. Pyyntö on JSON, jossa on query ja variables, kuten missä tahansa GraphQL-palvelussa — kunkin API:n välilehti Docs antaa valmiit kopioitavat esimerkit. Kun sovellus on julkaistu omassa osoitteessaan, sama palvelu vastaa myös sen osoitteen polussa /api/graphql.

Kuka voi kutsua endpointia:

Kuka kutsuu	Miten tunnistaudutaan	Mitä näkee
Sovelluksen näytöt	Sovelluksen käyttäjän istunto (automaattinen)	Julkaistut API:t
Ulkoiset järjestelmät	Otsake x-api-key — katso API-avaimet	Julkaistut API:t avaimen scopen sisällä
Rakentajat	Istunto alustalla	Julkaistut API:t JA luonnokset (luonnokseksi merkittyinä)
Anonyymit	Ei mitään	Vain julkiset API:t

#Taulu-API:n luominen

1. Luo API (Uusi API) nimellä, joka toimii operaatioiden perustana — esimerkiksi contas.
2. Paina välilehdellä Rakenna, osiossa Pipeline, painiketta Taulu. Taulu-lohko täyttää koko pipelinen — se ei yhdisty SQL-, HTTP- tai Skripti-vaiheisiin.
3. Valitse taulu valitsimella Valitse taulu… — taulut näkyvät tietolähteittäin ryhmiteltyinä, haulla taulun tai tietolähteen nimellä.
4. Aktivoi Julkaistut toiminnot ja säädä Mukana olevat kentät (katso alla).
5. Tallenna. Julkaisua varten tarvitaan valittu taulu ja vähintään yksi aktiivinen toiminto.

#Julkaistut toiminnot

Jokainen aktiivinen toiminto generoi operaation schemaan, nimi johdettuna perustasta — API:lle contas:

Toiminto	Generoitu operaatio	Mitä se tekee
Select	getContas (query)	Lista suodattimineen/järjestämisineen/sivutuksineen. Tuo mukanaan countContas-kentän, kokonaismäärän.
Insert	addContas (mutation)	Luo rivin.
Update	updateContas (mutation)	Päivittää rivin pääavaimella — osittain: muuttaa vain sen, minkä lähetät.
Delete	deleteContas (mutation)	Poistaa rivin pääavaimella ja palauttaa true.

Rivi Julkinen pääsy (ilman istuntoa) ohjaa, toiminto toiminnolta, mitä julkiset näytöt voivat kutsua — yksityiskohdat sivulla Julkiset API:t.

#Mukana olevat kentät

Puu Mukana olevat kentät määrittää vastauksen muodon: poista valinta kentistä, joita et halua paljastaa, ja laajenna navigointikentät sisällyttääksesi suhteessa olevat entiteetit — rekursiivisesti, kuten visuaalisessa GraphQL-editorissa. API:ssa contas navigaattorin contactos laajentaminen antaa asiakkaille mahdollisuuden pyytää kunkin asiakkuuden yhteyshenkilöt samassa kutsussa.

#Datan lukeminen: suodattimet, järjestäminen, sivutus

Listaquery hyväksyy neljä argumenttia: where, order, take ja skip. Täydellinen esimerkki Asiakashallinta-sovelluksessa:

query {
  getContas(
    where: { cidade: { eq: "Lisboa" }, estado: { neq: "ARQUIVADA" } }
    order: [{ nome: ASC }]
    take: 20
    skip: 0
  ) {
    id
    nome
    cidade
    contactos {
      nome
      email
    }
  }
}

#Argumentti where

Jokainen suodatettava kenttä hyväksyy operaattoreita tyypin mukaan:

Kentän tyyppi	Operaattorit
Teksti (ja enumit)	eq, neq, contains, startsWith, endsWith, gt, gte, lt, lte, in, nin
Numerot (Int, Float)	eq, neq, gt, gte, lt, lte, in, nin
Boolean	eq, neq
ID	eq, neq, in, nin

Ja kaksi yhdistäjää yhdistelmäehdoille: and ja or, jotka saavat suodatinlistoja.

where: {
  or: [
    { cidade: { eq: "Lisboa" } }
    { cidade: { eq: "Porto" } }
  ]
  valorAnual: { gte: 10000 }
}

Hyödyllisiä sääntöjä:

• eq: null löytää tietueet, joiden kenttä on tyhjä; neq: null täytetyt.
• Päivämäärävälit: ISO-tekstinä tallennetut päivämäärät (esim. 2026-08-11) järjestyvät aakkosissa kuten ajassa, joten gt/lt/gte/lte tekstillä riittävät välien suodattamiseen — dataCriacao: { gte: "2026-01-01", lt: "2026-07-01" }.
• in saa listan arvoja; nin sulkee sen pois.
• Suodattimen arvot menevät tietokantaan aina parametreina — contains pahantahtoisella tekstillä ei ole riski.
• contains, startsWith ja endsWith hakevat tekstiä täsmälleen kirjoitetussa muodossa: % tai _ on tekstiä eikä jokerimerkki, eikä kirjainkoko vaikuta missään tietokannassa ("ana" löytää "Ana").

#Järjestäminen ja sivutus

• order on lista muotoa { kenttä: ASC } tai { kenttä: DESC } — useat kohteet järjestävät usealla kentällä, annetussa järjestyksessä.
• take rajaa rivien määrän (katto 10 000 pyyntöä kohden) ja skip ohittaa ensimmäiset N — yhdessä ne muodostavat klassisen sivutuksen.

#Kokonaismäärä: count

Jokainen Taulu-API, jossa Select on aktiivinen, saa myös kentän count<Nimi>, joka palauttaa SAMAN where-ehdon rivien kokonaismäärän. Sivutetun taulukon luonteva pari on pyytää sivu ja kokonaismäärä yhdessä operaatiossa, aliaksilla:

query {
  items: getContas(take: 10, skip: 0) { id nome }
  total: countContas
}

Suodattimen kanssa välitä sama where molemmille kentille — kokonaismäärä laskee täsmälleen ne rivit, jotka lista palauttaisi ilman sivutusta.

#Datan kirjoittaminen

• addContas saa mukana olevat kentät argumentteina (taulun pakolliset ovat pakollisia mutationissa). Joissakin tietokannoissa vastaus on luotu rivi; toisissa true — API:n välilehti Docs näyttää tarkan muodon sinun tapauksessasi. Ei-tyhjä sarake, jolla on oletusarvo tietokannassa tai jonka tietokanta tuottaa, on valinnainen: jos et lähetä sitä, tietokannan arvo jää voimaan.
• updateContas saa pääavaimen (pakollinen) ja loput kentät valinnaisina — se päivittää vain sen, minkä lähetät — ja palauttaa päivitetyn rivin.
• deleteContas saa pääavaimen ja palauttaa true.

mutation ($nome: String!, $cidade: String) {
  addContas(nome: $nome, cidade: $cidade) {
    id
    nome
  }
}

Päivämäärä-ja-aika-sarake ilman aikavyöhykettä (timestamp, datetime) lähtee API:sta sellaisena kuin se on tietokannassa, ISO-muodossa ilman aikavyöhykettä (2026-09-25T09:30:00): se on sinne kirjoitettu kellonaika, ja se saapuu samanlaisena jokaiselle lukijalle aikavyöhykkeestä riippumatta. Pelkän päivän sarake lähtee päivänä (2026-09-25). Aikavyöhykkeellinen sarake (timestamptz, datetimeoffset, MySQL:n timestamp) lähtee ajanhetkenä, ISO-muodossa aikavyöhykkeen kanssa (2026-09-25T09:30:00.000Z), ja näytöt näyttävät sen lukijan aikavyöhykkeessä. Pipeline-API:n SQL-vaiheen palauttama Date lähtee myös ISO-muodossa aikavyöhykkeen kanssa. Näytöt näyttävät ne kaikki sovelluksen kielellä. Väärän tyyppinen arvo hyväksytään, kun epäselvyyttä ei ole: ”12” Int-kenttään, 1000 String-kenttään, ”true” Boolean-kenttään.

Kolme kirjoitusten sääntöä lisää:

• Perusavain voi kulkea myös add-kutsussa. Tietokannan luomalla avaimella se jätetään pois; luonnollisella avaimella (nimikekoodi, maakoodi) tietue luodaan näin.
• update tietueeseen, jota ei ole tai joka on kutsujan laajuuden ulkopuolella, ei muuta mitään ja palauttaa null; delete samoissa oloissa palauttaa false.
• Tietokannan hylkäys (toistuva avain, tietue, josta muut riippuvat, tyhjä pakollinen kenttä, liian pitkä arvo) saapuu selkeänä viestinä, kentän kanssa, kun tietokanta kertoo sen.

Pyyntö voi sisäkkäistää enintään 12 relaatiotasoa ja käyttää enintään 100 aliasta. Relaatiot luetaan erissä: samaan aikaan pyydetyt rivit menevät yhteen kyselyyn.

#Enumit

Enum paljastaa kiinteän arvojoukon GraphQL-schemassa — asiakkuuden tilan, myyntimahdollisuuden vaiheen. Niitä hallitaan sivulla API:t, välilehdellä Enumit:

1. Paina Uusi enum.
2. Anna nimi (esim. EstadoConta) ja, jos siitä on apua, kuvaus.
3. Lisää arvoja painikkeella Lisää arvo — jokaisella arvolla on tunniste (value) sekä valinnaiset label ja väri. Näytöt käyttävät väriä ja labelia; value on se, mikä kulkee API:ssa.
4. Tallenna.

Enumia käytetään kahdessa paikassa: mallin kentän tyyppinä (kenttä alkaa hyväksyä vain ne arvot, ja suodattimissa se käyttäytyy kuten teksti) ja API:n argumentin tyyppinä. Schemassa asiakkaat näkevät enumin arvoineen — testiympäristön automaattinen täydennys ehdottaa niitä.

Enum-arvoa kirjoitettaessa API hyväksyy scheman näyttämän nimen ilman lainausmerkkejä (estado: Em_curso) ja myös tallennetun arvon lainausmerkeissä (estado: "Em curso"). Näin lomakkeet ja keplin.api.mutate sen lähettävät. Arvo, joka ei kuulu enumiin, hylätään edelleen.

#Scheman tutkiminen GraphiQL:ssä

Minkä tahansa API:n välilehti Testaa sisältää GraphiQL:n — sovelluksen endpointin interaktiivisen ympäristön. Kirjoitat operaation vasemmalle, suoritat, ja näet vastauksen oikealla; automaattinen täydennys tuntee koko scheman, Taulu-operaatiot mukaan lukien. Painike Avaa ikkunassa antaa saman ympäristön koko ruudulle.

Koska olet kirjautunut alustalle, GraphiQL suorittaa kuten asiakas mutta näkee myös luonnokset — jokainen luonnostilassa oleva operaatio näkyy scheman dokumentaatiossa kuvauksella ”RASCUNHO”. Ja se vastaa sinun työversiostasi: se, mitä suunnittelet, on se, mitä testaat.

#Miksi ei…?

• Miksi en näe operaatiota getContas ulkoa? Joko API on luonnostilassa (julkaise se), tai Select-toiminto ei ole aktiivinen, tai avaimesi scopessa ei ole tätä endpointia.
• Miksi kenttä ei näy vastauksessa? Sitä ei ole valittu kohdassa Mukana olevat kentät — asiakkaat voivat valita vain sen, minkä API sisällyttää.
• Miksi addContas palauttaa true eikä riviä? Se riippuu taulun takana olevasta tietokannasta. Kun tarvitset rivin aina, jatka avaimella suodatetulla getContas-kutsulla.
• Miksi schema muuttui, vaikka en koskenut API:hin? Schema generoidaan mallista: uusien sarakkeiden tuominen, enumin muuttaminen tai entiteetin poistaminen käytöstä heijastuu API:in seuraavassa kutsussa.