Offentlige API-er

Som standard svarer GraphQL-endepunktet til en app bare den som identifiserer seg: en økt (fra skjermene i appen eller fra den som bygger) eller en API-nøkkel. Men det finnes legitime tilfeller av anonym tilgang — et kontaktskjema på nettstedet, en offentlig skjerm for statusoppslag, en åpen katalog. Til det finnes de offentlige API-ene: operasjoner du velger å åpne for forespørsler uten økt eller nøkkel.

Bryteren er alltid din, API for API — og, i Tabell-API-ene, operasjon for operasjon. Ingenting blir offentlig ved et uhell.

#Hva en anonym forespørsel er

En forespørsel til appens endepunkt (/api/graphql/gestao-clientes, eller /api/graphql på den publiserte adressen) uten øktcookie og uten headeren x-api-key. Det er det appens offentlige skjermer gjør — sider som serveres før innloggingen — og enhver ekstern klient du kaller uten legitimasjon.

#Gjøre et pipeline-API offentlig

1. Åpne API-et i builderen.
2. I toppteksten, slå på bryteren Offentlig (uten økt) — hintet bekrefter: «Tilgjengelig uten økt eller API-nøkkel — for appens offentlige skjermer.»
3. Lagre. API-et må også være Publisert — et utkast serveres aldri til anonyme, offentlig eller ikke.

#Gjøre operasjoner i et Tabell-API offentlige

I et Tabell-API er den offentlige tilgangen finere: per handling. I Tabell-blokken har linjen Offentlig tilgang (uten økt) en bryter per handling (Select, Insert, Update, Delete):

1. Aktiver først handlingen under Eksponerte handlinger — bare eksponerte handlinger kan være offentlige; å slå av en handling slår også av den offentlige tilgangen til den.
2. Slå på den offentlige bryteren bare for operasjonene de offentlige skjermene trenger. «Slå bare på det du trenger» — det er husets regel.
3. Lagre.

Et offentlig skjema for interesseregistrering, for eksempel, trenger offentlig Insert — og ikke noe mer: listen, redigeringen og slettingen blir stående bak økten.

#Hva de anonyme ser — og hva de ikke ser

Endepunktet behandler de anonyme forespørslene med et eget, strammere skjema:

• Bare de offentlige API-ene finnes. De øvrige vises ikke engang ved introspeksjon — ikke engang navnene. En anonym klarer ikke å liste opp det appen har av privat.
• Hver operasjon validerer tilgangen. Å kalle en ikke-offentlig operasjon i en anonym forespørsel returnerer feilen «Operation not available without a session» — selv om man kjenner navnet.
• Utkast aldri. Bare publiserte API-er.
• Det finnes et tak på forespørsler: 120 forespørsler per minutt, per app og per opprinnelsesadresse. Over taket er svaret 429 med headeren retry-after som sier hvor lenge man skal vente. Det holder i massevis for offentlige skjermer; det stanser grunnleggende misbruk.

#Kalle uten økt eller nøkkel

En anonym forespørsel er en vanlig POST, uten autentiseringsheadere:

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"}}'

Fanen Dokumentasjon i API-et gir deg det nøyaktige eksempelet — ignorer linjen med x-api-key der, den gjelder bare klienter med nøkkel.

#God praksis

Praksis	Hvorfor
Åpne et minimum av operasjoner	Hver offentlig operasjon er en flate eksponert mot verden.
I tabellene, foretrekk lesehandlinger — og opptalte felt	Treet Inkluderte felt gjelder også for anonyme: det som ikke er inkludert, kommer ikke ut.
Offentlige skrivinger med påkrevde argumenter og validering i pipelinen	En offentlig Insert godtar det den får tilsendt — valider i Skript-trinnet eller med regler i modellen.
Overvåk i Radar	De offentlige kjøringene registreres med tilgangsmodusen; unormale topper ses der.

#Hvorfor kan jeg ikke…?

• Jeg slo på bryteren, og den anonyme forespørselen feiler fortsatt. Se på tilstanden: API-et må være Publisert i tillegg til Offentlig — og, i en tabell, må den riktige handlingen ha den offentlige bryteren på.
• Hvorfor returnerer nettleseren en feil når jeg åpner endepunktet? Det interaktive miljøet (GraphiQL) på endepunktet krever økt på plattformen — det er et verktøy for den som bygger. Dataene bes om med POST, som i eksempelet over.
• Hvorfor får jeg 429? Du nådde det anonyme taket for adressen. Vent tiden i retry-after. Trenger integrasjonen din mer, bruk en API-nøkkel — grensene til en nøkkel er uavhengige av det anonyme taket.
• Respekterer en offentlig operasjon tillatelsene til brukerne av appen? En anonym er ikke en bruker — det finnes ikke noe bruker-dataomfang å håndheve. Eksponer i offentlige operasjoner bare data som virkelig kan tilhøre alle.