APIs publiques

Par défaut, l'endpoint GraphQL d'une app ne répond qu'à qui s'identifie : une session (des écrans de l'app ou de celui qui construit) ou une clé API. Mais il existe des cas légitimes d'accès anonyme — un formulaire de contact sur le site, un écran public de consultation d'état, un catalogue ouvert. C'est pour cela qu'existent les APIs publiques : des opérations que vous choisissez d'ouvrir aux requêtes sans session ni clé.

L'interrupteur est toujours le vôtre, API par API — et, dans les APIs de Table, opération par opération. Rien ne devient public par accident.

#Ce qu'est une requête anonyme

Une requête à l'endpoint de l'app (/api/graphql/gestao-clientes, ou /api/graphql à l'adresse publiée) sans cookie de session et sans header x-api-key. C'est ce que font les écrans publics de l'app — des pages servies avant la connexion — et n'importe quel client externe que vous appelez sans identifiants.

#Rendre publique une API de pipeline

1. Ouvrez l'API dans le constructeur.
2. Dans l'en-tête, activez l'interrupteur Publique (sans session) — l'aide le confirme : « Accessible sans session ni clé API — pour les écrans publics de l'app. »
3. Enregistrer. L'API doit aussi être Publiée — un brouillon n'est jamais servi à des anonymes, public ou non.

#Rendre publiques des opérations d'une API de Table

Dans une API de Table, l'accès public est plus fin : par action. Dans le bloc Table, la ligne Accès public (sans session) a un interrupteur par action (Select, Insert, Update, Delete) :

1. Activez d'abord l'action dans Actions exposées — seules les actions exposées peuvent être publiques ; désactiver une action désactive aussi son accès public.
2. N'activez l'interrupteur public que pour les opérations dont les écrans publics ont besoin. « N'activez que le nécessaire » — c'est la règle de la maison.
3. Enregistrer.

Un formulaire public d'enregistrement d'intérêt, par exemple, a besoin d'un Insert public — et de rien d'autre : la liste, la modification et la suppression restent derrière la session.

#Ce que les anonymes voient — et ce qu'ils ne voient pas

L'endpoint traite les requêtes anonymes avec un schéma propre, plus resserré :

• Seules les APIs publiques existent. Les autres n'apparaissent même pas par introspection — pas même les noms. Un anonyme ne peut pas lister ce que l'app a de privé.
• Chaque opération valide l'accès. Appeler une opération non publique dans une requête anonyme renvoie l'erreur « Operation not available without a session » — même si l'on en connaît le nom.
• Jamais de brouillons. Uniquement des APIs publiées.
• Il y a un plafond de requêtes : 120 requêtes par minute, par app et par adresse d'origine. Une fois le plafond dépassé, la réponse est 429 avec le header retry-after qui dit combien de temps attendre. C'est largement suffisant pour des écrans publics ; cela freine l'abus basique.

#Appeler sans session ni clé

Une requête anonyme est un POST normal, sans headers d'authentification :

curl -X POST 'https://votre-hote/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"}}'

L'onglet Docs de l'API vous donne l'exemple exact — ignorez-y la ligne du x-api-key, qui ne s'applique qu'aux clients avec une clé.

#Bonnes pratiques

Pratique	Pourquoi
Ouvrez le minimum d'opérations	Chaque opération publique est une surface exposée au monde.
Sur les tables, préférez des actions de lecture — et des champs comptés	L'arborescence Champs inclus vaut aussi pour les anonymes : ce qui n'est pas inclus ne sort pas.
Des écritures publiques avec des arguments obligatoires et de la validation dans le pipeline	Un Insert public accepte ce qu'on lui envoie — validez dans l'étape Script ou avec les règles du modèle.
Surveillez dans le Radar	Les exécutions publiques sont enregistrées avec le mode d'accès ; les pics anormaux s'y voient.

#Pourquoi ne… ?

• J'ai activé l'interrupteur et la requête anonyme échoue toujours. Regardez l'état : l'API doit être Publiée en plus de Publique — et, dans une table, la bonne action doit avoir son interrupteur public activé.
• Pourquoi le navigateur renvoie-t-il une erreur en ouvrant l'endpoint ? L'environnement interactif (GraphiQL) de l'endpoint demande une session sur la plateforme — c'est un outil pour qui construit. Les données se demandent par POST, comme dans l'exemple ci-dessus.
• Pourquoi est-ce que je reçois 429 ? Vous avez atteint le plafond anonyme de l'adresse. Attendez le temps du retry-after. Si votre intégration a besoin de plus, utilisez une clé API — les limites d'une clé sont indépendantes du plafond anonyme.
• Une opération publique respecte-t-elle les permissions des utilisateurs de l'app ? Un anonyme n'est pas un utilisateur — il n'y a pas de périmètre de données d'utilisateur à appliquer. N'exposez dans des opérations publiques que des données qui peuvent vraiment être à tout le monde.