APIs públicas

Por defecto, el endpoint GraphQL de una app solo responde a quien se identifica: una sesión (de las pantallas de la app o de quien construye) o una clave API. Pero hay casos legítimos de acceso anónimo — un formulario de contacto en el sitio, una pantalla pública de consulta de estado, un catálogo abierto. Para eso existen las APIs públicas: operaciones que eliges abrir a peticiones sin sesión ni clave.

El interruptor es siempre tuyo, API a API — y, en las APIs de Tabla, operación a operación. Nada queda público por accidente.

#Qué es una petición anónima

Una petición al endpoint de la app (/api/graphql/gestao-clientes, o /api/graphql en la dirección publicada) sin cookie de sesión y sin header x-api-key. Es lo que hacen las pantallas públicas de la app — páginas servidas antes del login — y cualquier cliente externo que llames sin credenciales.

#Hacer pública una API de pipeline

1. Abre la API en el constructor.
2. En la cabecera, activa el interruptor Pública (sin sesión) — la pista lo confirma: «Accesible sin sesión ni clave API — para pantallas públicas de la app.»
3. Guardar. La API también tiene que estar Publicada — un borrador nunca se sirve a anónimos, público o no.

#Hacer públicas operaciones de una API de Tabla

En una API de Tabla el acceso público es más fino: por acción. En el bloque Tabla, la fila Acceso público (sin sesión) tiene un interruptor por acción (Select, Insert, Update, Delete):

1. Activa primero la acción en Acciones expuestas — solo las acciones expuestas pueden ser públicas; desactivar una acción desactiva también su acceso público.
2. Activa el interruptor público solo de las operaciones que las pantallas públicas necesitan. «Activa solo lo necesario» — es la regla de la casa.
3. Guardar.

Un formulario público de registro de interés, por ejemplo, necesita Insert público — y nada más: la lista, la edición y la eliminación quedan detrás de la sesión.

#Lo que los anónimos ven — y lo que no ven

El endpoint trata las peticiones anónimas con un schema propio, más apretado:

• Solo las APIs públicas existen. Las demás no aparecen ni por introspección — ni los nombres. Un anónimo no puede listar lo que la app tiene de privado.
• Cada operación valida el acceso. Llamar a una operación no pública en una petición anónima devuelve el error «Operation not available without a session» — aunque se sepa el nombre.
• Borradores nunca. Solo APIs publicadas.
• Hay un techo de peticiones: 120 peticiones por minuto, por app y por dirección de origen. Pasado el techo, la respuesta es 429 con el header retry-after diciendo cuánto esperar. Sobra para pantallas públicas; frena el abuso básico.

#Llamar sin sesión ni clave

Una petición anónima es un POST normal, sin headers de autenticación:

curl -X POST 'https://tu-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 pestaña Docs de la API te da el ejemplo exacto — ignora ahí la línea del x-api-key, que solo se aplica a clientes con clave.

#Buenas prácticas

Práctica	Por qué
Abre el mínimo de operaciones	Cada operación pública es superficie expuesta al mundo.
En las tablas, prefiere acciones de lectura — y campos contados	El árbol Campos incluidos también vale para anónimos: lo que no está incluido, no sale.
Escrituras públicas con argumentos obligatorios y validación en el pipeline	Un Insert público acepta lo que le envíen — valida en el paso Script o con reglas del modelo.
Vigila en el Radar	Las ejecuciones públicas quedan registradas con el modo de acceso; los picos anómalos se ven ahí.

#¿Por qué no…?

• Activé el interruptor y la petición anónima sigue fallando. Mira el estado: la API tiene que estar Publicada además de Pública — y, en una tabla, la acción correcta tiene que tener el interruptor público activado.
• ¿Por qué el navegador devuelve un error al abrir el endpoint? El entorno interactivo (GraphiQL) del endpoint pide sesión en la plataforma — es una herramienta de quien construye. Los datos se piden por POST, como en el ejemplo de arriba.
• ¿Por qué recibo 429? Alcanzaste el techo anónimo de la dirección. Espera el tiempo del retry-after. Si tu integración necesita más, usa una clave API — los límites de una clave son independientes del techo anónimo.
• ¿Una operación pública respeta los permisos de los usuarios de la app? Un anónimo no es un usuario — no hay ámbito de datos de usuario que aplicar. Expón en operaciones públicas solo datos que puedan ser de verdad de todos.