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.

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

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

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