APIs públicas

Por omissão, o endpoint GraphQL de uma app só responde a quem se identifica: uma sessão (dos ecrãs da app ou de quem constrói) ou uma API key. Mas há casos legítimos de acesso anónimo — um formulário de contacto no site, um ecrã público de consulta de estado, um catálogo aberto. Para isso existem as APIs públicas: operações que escolhes abrir a pedidos sem sessão nem chave.

O interruptor é sempre teu, API a API — e, nas APIs de Tabela, operação a operação. Nada fica público por acidente.

#O que é um pedido anónimo

Um pedido ao endpoint da app (/api/graphql/gestao-clientes, ou /api/graphql no endereço publicado) sem cookie de sessão e sem header x-api-key. É o que fazem os ecrãs públicos da app — páginas servidas antes do login — e qualquer cliente externo que chames sem credenciais.

#Tornar pública uma API de pipeline

1. Abre a API no construtor.
2. No cabeçalho, liga o interruptor Pública (sem sessão) — a dica confirma: "Acessível sem sessão nem API key — para ecrãs públicos da app."
3. Gravar. A API também tem de estar Publicada — um rascunho nunca é servido a anónimos, público ou não.

#Tornar públicas operações de uma API de Tabela

Numa API de Tabela o acesso público é mais fino: por acção. No bloco Tabela, a linha Acesso público (sem sessão) tem um interruptor por acção (Select, Insert, Update, Delete):

1. Activa primeiro a acção em Acções expostas — só acções expostas podem ser públicas; desligar uma acção desliga também o acesso público dela.
2. Liga o interruptor público apenas das operações de que os ecrãs públicos precisam. "Liga apenas o necessário" — é a regra da casa.
3. Gravar.

Um formulário público de registo de interesse, por exemplo, precisa de Insert público — e de mais nada: a lista, a edição e a remoção ficam atrás da sessão.

#O que os anónimos vêem — e o que não vêem

O endpoint trata os pedidos anónimos com um schema próprio, mais apertado:

• Só as APIs públicas existem. As restantes não aparecem sequer por introspecção — nem os nomes. Um anónimo não consegue listar o que a app tem de privado.
• Cada operação valida o acesso. Chamar uma operação não-pública num pedido anónimo devolve o erro "Operation not available without a session" — mesmo que se saiba o nome.
• Rascunhos nunca. Só APIs publicadas.
• Há um tecto de pedidos: 120 pedidos por minuto, por app e por endereço de origem. Passado o tecto, a resposta é 429 com o header retry-after a dizer quanto esperar. Chega de sobra para ecrãs públicos; trava abuso básico.

#Chamar sem sessão nem chave

Um pedido anónimo é um POST normal, sem headers de autenticação:

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

O separador Docs da API dá-te o exemplo exacto — ignora aí a linha do x-api-key, que só se aplica a clientes com chave.

#Boas práticas

Prática	Porquê
Abre o mínimo de operações	Cada operação pública é superfície exposta ao mundo.
Nas tabelas, prefere acções de leitura — e campos contados	A árvore Campos incluídos também vale para anónimos: o que não está incluído, não sai.
Escritas públicas com argumentos obrigatórios e validação no pipeline	Um Insert público aceita o que lhe enviarem — valida no passo Script ou com regras do modelo.
Vigia no Radar	As execuções públicas ficam registadas com o modo de acesso; picos anómalos vêem-se lá.

#Porque não…?

• Liguei o interruptor e o pedido anónimo continua a falhar. Vê o estado: a API tem de estar Publicada além de Pública — e, numa tabela, a acção certa tem de ter o interruptor público ligado.
• Porque devolve o browser um erro ao abrir o endpoint? O ambiente interactivo (GraphiQL) do endpoint pede sessão na plataforma — é uma ferramenta de quem constrói. Os dados pedem-se por POST, como no exemplo acima.
• Porque recebo 429? Atingiste o tecto anónimo do endereço. Espera o tempo do retry-after. Se a tua integração precisa de mais, usa uma API key — os limites de uma key são independentes do tecto anónimo.
• Uma operação pública respeita as permissões dos utilizadores da app? Um anónimo não é um utilizador — não há âmbito de dados de utilizador para aplicar. Expõe em operações públicas apenas dados que possam mesmo ser de todos.