Exponiendo endpoints públicos y privados
GraphQL tradicionalmente trata sobre exponer un único endpoint, normalmente en https://mysite.com/graphql.
Gato GraphQL expande esta noción, permitiéndonos exponer múltiples endpoints personalizados, cada uno adaptado a una necesidad específica. Por ejemplo, podemos exponer endpoints:
/internaly/public/apps/mobiley/apps/website/clientsy/visitors/development,/stagingy/production/teams/development,/teams/testingy/teams/marketing/clients/A,/clients/Byclients/Z- cualquier combinación de ellos
Gato GraphQL también soporta Consultas Persistidas, que son endpoints donde la consulta GraphQL está predefinida y almacenada en el servidor.
Esta guía presenta sugerencias sobre cómo y cuándo usar cada endpoint.
Además de asegurar tus endpoints de la API de Gato GraphQL, te recomendamos que siempre fortalezcas la seguridad de tu sitio WordPress utilizando un plugin de seguridad dedicado, como WP Security Ninja.
Los endpoints se configuran vía una Configuración del Esquema, donde definimos:
- Establecer el esquema como público o privado
- Habilitar elementos de datos "sensibles"
- Aplicar namespacing al esquema
- Usar mutaciones anidadas
- Definir cabeceras de respuesta
- Conceder acceso a los elementos del esquema mediante listas de control de acceso
- Configurar el caché HTTP
- Muchas otras
Si tenemos una configuración que queremos aplicar a todos o a la mayoría de los endpoints, podemos definir una Configuración del Esquema por defecto.
Cuándo usar el endpoint único
El endpoint único es siempre público, expuesto por defecto en /graphql.
Gato GraphQL se gestiona mediante "módulos", cada uno de los cuales ofrece alguna funcionalidad o extensión del esquema GraphQL, y que pueden habilitarse y deshabilitarse según se necesite.
Para fortalecer la seguridad de nuestra API, es una buena práctica deshabilitar módulos que extienden el esquema GraphQL (como los módulos "Posts", "Users", "Comments", "Blocks", etc.) cuando no se necesitan, para asegurarse de que esos datos nunca se expondrán en primer lugar.
En particular, si la API no está destinada a mutar datos (es decir, crear o actualizar recursos), es una buena práctica deshabilitar el módulo "Mutations". Hacerlo deshabilitará a su vez todas las extensiones que proporcionen alguna mutación (como los módulos "Post Mutations", "Comment Mutations", etc.), y estas mutaciones nunca se expondrán en el esquema GraphQL.
El endpoint único se recomienda cuando:
- Necesitamos recuperar datos para alimentar una única característica, y
- La web WordPress no es accesible al Internet abierto (es decir, se está ejecutando en un portátil de desarrollo, o detrás de un firewall)
Este es el caso, por ejemplo, para construir un sitio headless (usando Next.js, Gatsby, u otros).
Cuándo usar endpoints personalizados públicos
Los endpoints personalizados son similares al endpoint único, pero podemos tener muchos de ellos, cada uno expuesto bajo su propia URL graphql/{custom-endpoint-slug}/, con cada uno teniendo una configuración diferente.
Los endpoints personalizados ofrecen seguridad por oscuridad, ya que solo el objetivo previsto debería conocer la existencia del endpoint personalizado y su URL.
Para reforzar la seguridad de la API, podemos usar la extensión Access Control para conceder acceso al endpoint solo cuando:
- El usuario está autenticado (o no)
- El usuario tiene cierto rol
- El usuario tiene cierta capacidad
- El visitante viene de una IP permitida (vía la extensión Control de Acceso: IP del Visitante)
Cada endpoint personalizado puede tener su propia lista de control de acceso, siendo así accesible solo por su usuario específico previsto.
Los endpoints personalizados se recomiendan cuando necesitamos gestionar y personalizar los accesos a la API, ya sea por distintas aplicaciones, equipos, clientes o cualquier otro.
Cuándo usar endpoints personalizados privados
Gato GraphQL implementa los endpoints personalizados mediante Custom Post Types (CPTs). Esto nos permite publicar el endpoint personalizado como privado (y también como protegido por contraseña), haciendo así el endpoint personalizado accesible solo a los usuarios autenticados que tengan derecho a acceder a esa entrada personalizada, y a nadie más.
Este método se recomienda cuando el endpoint GraphQL está destinado a ser usado solo por el administrador del sitio (como cuando se usa GraphQL para ejecutar tareas de administración). Al bloquear completamente el acceso al endpoint desde el exterior, estaremos reforzando la seguridad del sitio.
Cuándo usar consultas persistidas públicas
Las consultas persistidas son endpoints, cada uno con su propia URL, pero la consulta GraphQL ya está definida en el lado del servidor, por lo que la respuesta también está predefinida (puede hacerse dinámica definiendo variables, a satisfacer mediante parámetros de URL).
Las consultas persistidas son similares a los endpoints REST, pero usamos el lenguaje GraphQL para componer la consulta, y podemos publicarla directamente desde wp-admin. No es necesario desplegar ningún código PHP para publicar una consulta persistida.
Como las consultas persistidas no requieren pasar la consulta GraphQL en el cuerpo de la petición, son naturalmente adecuadas para ser accedidas mediante GET en lugar de POST.
(El endpoint único y los endpoints personalizados también pueden accederse mediante GET añadiendo el parámetro ?query={ GraphQL query } al endpoint.)
Podemos beneficiarnos de esto y hacer la API más rápida mediante el caché HTTP estándar, cacheando la respuesta GraphQL en el lado del cliente o en etapas intermedias entre el cliente y el servidor (como una CDN).
Esto se consigue mediante la extensión Cache Control, que calcula y emite automáticamente el valor max-age de la respuesta basándose en los campos y directivas presentes en la consulta.
Se recomienda usar consultas persistidas siempre que sea posible, ya que aumentan sustancialmente la seguridad de nuestros sitios.
Esto es porque todos los datos que necesitan estar disponibles para nuestra aplicación pueden ya exponerse mediante consultas persistidas. Entonces, podemos omitir la exposición del endpoint único de GraphQL (o cualquier endpoint personalizado), eliminando así la posibilidad de que los usuarios pudieran acceder a datos privados que dejamos expuestos (por error o no).
Cuándo usar consultas persistidas privadas
Similar a los endpoints personalizados, las consultas persistidas son CPTs, por lo que podemos publicarlas como privadas (o protegidas por contraseña), haciéndolas accesibles solo a los usuarios autenticados que tengan derecho a acceder a ellas, y a nadie más.
Se recomienda usar estas siempre que la consulta esté destinada solo para uso interno, como cuando se buscan datos de WordPress para nuestro propio uso.