API pubbliche

Per impostazione predefinita, l'endpoint GraphQL di un'app risponde solo a chi si identifica: una sessione (delle schermate dell'app o di chi costruisce) oppure una chiave API. Ma ci sono casi legittimi di accesso anonimo — un modulo di contatto sul sito, una schermata pubblica di consultazione di stato, un catalogo aperto. Per questo esistono le API pubbliche: operazioni che scegli di aprire a richieste senza sessione né chiave.

L'interruttore è sempre tuo, API per API — e, nelle API di Tabella, operazione per operazione. Nulla diventa pubblico per caso.

#Che cos'è una richiesta anonima

Una richiesta all'endpoint dell'app (/api/graphql/gestao-clientes, oppure /api/graphql sull'indirizzo pubblicato) senza cookie di sessione e senza header x-api-key. È ciò che fanno le schermate pubbliche dell'app — pagine servite prima del login — e qualsiasi client esterno che chiami senza credenziali.

#Rendere pubblica un'API di pipeline

1. Apri l'API nel costruttore.
2. Nell'intestazione, attiva l'interruttore Pubblica (senza sessione) — il suggerimento conferma: "Accessibile senza sessione né chiave API — per le schermate pubbliche dell' app."
3. Salva. L'API deve anche essere Pubblicata — una bozza non viene mai servita agli anonimi, pubblica o meno.

#Rendere pubbliche le operazioni di un'API di Tabella

In un'API di Tabella l'accesso pubblico è più fine: per azione. Nel blocco Tabella, la riga Accesso pubblico (senza sessione) ha un interruttore per azione (Select, Insert, Update, Delete):

1. Attiva prima l'azione in Azioni esposte — solo le azioni esposte possono essere pubbliche; disattivare un'azione disattiva anche il suo accesso pubblico.
2. Attiva l'interruttore pubblico soltanto delle operazioni di cui le schermate pubbliche hanno bisogno. "Attiva solo ciò che serve" — è la regola della casa.
3. Salva.

Un modulo pubblico di registrazione di interesse, per esempio, ha bisogno di Insert pubblico — e di nient'altro: l'elenco, la modifica e l'eliminazione restano dietro la sessione.

#Che cosa vedono gli anonimi — e che cosa non vedono

L'endpoint tratta le richieste anonime con uno schema proprio, più stretto:

• Esistono solo le API pubbliche. Le altre non appaiono nemmeno per introspezione — nemmeno i nomi. Un anonimo non riesce a elencare ciò che l' app ha di privato.
• Ogni operazione valida l'accesso. Chiamare un'operazione non pubblica in una richiesta anonima restituisce l'errore "Operation not available without a session" — anche se se ne conosce il nome.
• Le bozze mai. Solo le API pubblicate.
• C'è un tetto di richieste: 120 richieste al minuto, per app e per indirizzo di origine. Superato il tetto, la risposta è 429 con l'header retry-after che dice quanto aspettare. Basta e avanza per le schermate pubbliche; ferma l'abuso di base.

#Chiamare senza sessione né chiave

Una richiesta anonima è un POST normale, senza header di autenticazione:

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

La scheda Docs dell'API ti dà l'esempio esatto — ignora lì la riga dell' x-api-key, che si applica solo ai client con chiave.

#Buone pratiche

Pratica	Perché
Apri il minimo di operazioni	Ogni operazione pubblica è superficie esposta al mondo.
Nelle tabelle, preferisci le azioni di lettura — e campi contati	L'albero Campi inclusi vale anche per gli anonimi: ciò che non è incluso, non esce.
Scritture pubbliche con argomenti obbligatori e validazione nella pipeline	Un Insert pubblico accetta ciò che gli inviano — valida nel passaggio Script o con le regole del modello.
Sorveglia nel Radar	Le esecuzioni pubbliche restano registrate con la modalità di accesso; i picchi anomali si vedono lì.

#Perché no…?

• Ho attivato l'interruttore e la richiesta anonima continua a fallire. Guarda lo stato: l'API deve essere Pubblicata oltre che Pubblica — e, in una tabella, l'azione giusta deve avere l'interruttore pubblico attivo.
• Perché il browser restituisce un errore aprendo l'endpoint? L'ambiente interattivo (GraphiQL) dell'endpoint richiede una sessione sulla piattaforma — è uno strumento di chi costruisce. I dati si chiedono via POST, come nell' esempio qui sopra.
• Perché ricevo 429? Hai raggiunto il tetto anonimo dell'indirizzo. Aspetta il tempo del retry-after. Se la tua integrazione ha bisogno di più, usa una chiave API — i limiti di una chiave sono indipendenti dal tetto anonimo.
• Un'operazione pubblica rispetta i permessi degli utenti dell' app? Un anonimo non è un utente — non c'è un ambito di dati di utente da applicare. Esponi in operazioni pubbliche soltanto dati che possano davvero essere di tutti.