Julkiset API:t

Oletuksena sovelluksen GraphQL-endpoint vastaa vain sille, joka tunnistautuu: istunnolla (sovelluksen näyttöjen tai rakentajan) tai API-avaimella. Mutta anonyymille pääsylle on oikeutettuja tapauksia — yhteydenottolomake sivustolla, julkinen tilan kyselynäyttö, avoin katalogi. Niitä varten ovat julkiset API:t: operaatiot, jotka päätät avata pyynnöille ilman istuntoa ja avainta.

Kytkin on aina sinun, API API:lta — ja Taulu-API:ssa operaatio operaatiolta. Mikään ei tule julkiseksi vahingossa.

#Mikä on anonyymi pyyntö

Pyyntö sovelluksen endpointiin (/api/graphql/gestao-clientes, tai /api/graphql julkaistussa osoitteessa) ilman istuntoevästettä ja ilman otsaketta x-api-key. Sitä tekevät sovelluksen julkiset näytöt — sivut, jotka tarjoillaan ennen kirjautumista — ja mikä tahansa ulkoinen asiakas, jota kutsut ilman tunnistetietoja.

#Pipeline-API:n tekeminen julkiseksi

1. Avaa API rakentimessa.
2. Kytke ylätunnisteessa päälle kytkin Julkinen (ilman istuntoa) — vihje vahvistaa: ”Käytettävissä ilman istuntoa ja API-avainta — sovelluksen julkisia näyttöjä varten.”
3. Tallenna. API:n on oltava myös Julkaistu — luonnosta ei koskaan tarjoilla anonyymeille, julkinen tai ei.

#Taulu-API:n operaatioiden tekeminen julkisiksi

Taulu-API:ssa julkinen pääsy on hienojakoisempaa: toiminnoittain. Taulu-lohkossa rivillä Julkinen pääsy (ilman istuntoa) on kytkin toimintoa kohden (Select, Insert, Update, Delete):

1. Aktivoi toiminto ensin kohdassa Julkaistut toiminnot — vain julkaistut toiminnot voivat olla julkisia; toiminnon kytkeminen pois kytkee pois myös sen julkisen pääsyn.
2. Kytke julkinen kytkin päälle vain niistä operaatioista, joita julkiset näytöt tarvitsevat. ”Kytke päälle vain tarpeellinen” — se on talon sääntö.
3. Tallenna.

Esimerkiksi julkinen kiinnostuksen rekisteröintilomake tarvitsee julkisen Insert-toiminnon — eikä mitään muuta: lista, muokkaus ja poisto jäävät istunnon taakse.

#Mitä anonyymit näkevät — ja mitä eivät

Endpoint käsittelee anonyymit pyynnöt omalla, tiukemmalla schemalla:

• Vain julkiset API:t ovat olemassa. Loput eivät näy edes introspektiossa — eivät edes nimet. Anonyymi ei pysty listaamaan, mitä yksityistä sovelluksessa on.
• Jokainen operaatio validoi pääsyn. Ei-julkisen operaation kutsuminen anonyymissä pyynnössä palauttaa virheen ”Operation not available without a session” — vaikka nimi tiedettäisiin.
• Luonnoksia ei koskaan. Vain julkaistut API:t.
• Pyynnöillä on katto: 120 pyyntöä minuutissa, sovellusta ja lähdeosoitetta kohden. Katon ylityttyä vastaus on 429 otsakkeella retry-after, joka kertoo, kauanko odottaa. Se riittää julkisille näytöille mainiosti; se pysäyttää perusväärinkäytön.

#Kutsuminen ilman istuntoa ja avainta

Anonyymi pyyntö on tavallinen POST, ilman tunnistautumisotsakkeita:

curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -d '{"query":"mutation ($nome: String!, $email: String!) { registarInteresse(nome: $nome, email: $email) }","variables":{"nome":"Ana Silva","email":"ana@exemplo.pt"}}'

API:n välilehti Docs antaa täsmällisen esimerkin — ohita siellä x-api-key-rivi, joka koskee vain avaimellisia asiakkaita.

#Hyvät käytännöt

Käytäntö	Miksi
Avaa mahdollisimman vähän operaatioita	Jokainen julkinen operaatio on maailmalle altistettua pintaa.
Suosi tauluissa lukutoimintoja — ja punnittuja kenttiä	Puu Mukana olevat kentät pätee myös anonyymeille: se, mikä ei ole mukana, ei lähde ulos.
Julkiset kirjoitukset pakollisilla argumenteilla ja validoinnilla pipelinessä	Julkinen Insert hyväksyy sen, mitä sille lähetetään — validoi Skripti-vaiheessa tai mallin säännöillä.
Vahdi Radarissa	Julkiset suoritukset kirjataan pääsytiloineen; poikkeavat piikit näkyvät siellä.

#Miksi ei…?

• Kytkin päällä ja anonyymi pyyntö epäonnistuu yhä. Katso tila: API:n on oltava Julkaistu sen lisäksi että se on Julkinen — ja taulussa oikealla toiminnolla on oltava julkinen kytkin päällä.
• Miksi selain palauttaa virheen, kun avaan endpointin? Endpointin interaktiivinen ympäristö (GraphiQL) vaatii istunnon alustalla — se on rakentajien työkalu. Data pyydetään POST-kutsulla, kuten yllä olevassa esimerkissä.
• Miksi saan 429? Saavutit osoitteen anonyymin katon. Odota retry-after-otsakkeen ajan. Jos integraatiosi tarvitsee enemmän, käytä API-avainta — avaimen rajat ovat riippumattomia anonyymistä katosta.
• Noudattaako julkinen operaatio sovelluksen käyttäjien käyttöoikeuksia? Anonyymi ei ole käyttäjä — ei ole käyttäjän datarajausta sovellettavaksi. Paljasta julkisissa operaatioissa vain dataa, joka voi todella olla kaikkien.