Drupal como backend: GraphQL, JSON:API, RESTful y el costoso error oculto en la elección de la API

Una vez, un CTO me preguntó, a mitad de una reunión de planificación de Drupal desacoplado: “Entonces, ¿qué API deberíamos usar?”

La sala quedó en silencio por un segundo. Frontend quería GraphQL. Backend quería JSON:API. Un proveedor de integración ya había asumido REST. El product owner solo quería que la aplicación móvil dejara de esperar a los lanzamientos del sitio web.

Esa pequeña pregunta suele sonar técnica. No lo es. Es una pregunta de gobernanza, una pregunta de presupuesto y, a veces, una pregunta de contratación disfrazada con sudadera de desarrollador.

Drupal puede ser un backend muy capaz para productos desacoplados. Ya cuenta con contenido estructurado, roles, permisos, flujos de trabajo, revisiones, traducciones, gestión de medios, taxonomía y un ecosistema maduro de módulos. La parte incómoda es decidir cómo sale ese contenido de Drupal. El núcleo de Drupal tiene soporte nativo para JSON:API, GraphQL está disponible mediante un módulo contribuido, y el módulo RESTful Web Services de Drupal sigue siendo una opción para endpoints personalizados de estilo recurso. La propia documentación desacoplada de Drupal expone claramente la división: JSON:API está en el núcleo, GraphQL es contribuido, y Drupal puede exponer contenido a un frontend externo mediante APIs.

Y aun así, los equipos siguen eligiendo mal.

Eligen GraphQL porque suena moderno. Eligen REST porque todo el mundo lo ha usado. Eligen JSON:API porque está ahí. Nada de eso es una estrategia.

Esta es la versión más clara: para la mayoría de las plataformas de contenido respaldadas por Drupal, JSON:API debería ser el punto de partida predeterminado. GraphQL debería ganarse. REST debería reservarse para los casos en los que los otros dos sean demasiado amplios o demasiado opinados.

Eso molestará a algunas personas. Bien.

Empieza con el ganador aburrido: JSON:API

JSON:API es aburrido de la mejor manera posible.

El módulo JSON:API del núcleo de Drupal implementa la especificación JSON:API para entidades de Drupal. Ofrece una forma sin configuración, opinada, de exponer operaciones CRUD para el contenido del sitio, y está integrado con los sistemas Entity API, Field API, caché, autenticación y autorización de Drupal.

Esa frase contiene la parte que debería importarles a los ejecutivos: módulo del núcleo.

El núcleo importa. El núcleo suele significar menos sorpresas con proveedores, una planificación de mantenimiento más sencilla, una postura de seguridad más clara y menos riesgo de “necesitamos al único contratista que entiende la capa de API personalizada”. La documentación de JSON:API de Drupal dice que el módulo expone APIs alrededor de tipos de entidad y bundles, admite filtrado, includes, paginación, ordenación, revisiones, traducciones, GET, POST, PATCH, DELETE, subida de archivos y personalización de recursos mediante eventos.

Un ejemplo práctico: imagina una empresa de medios con artículos, autores, temas, teasers para páginas de aterrizaje e imágenes. El equipo frontend necesita páginas de artículos en Next.js. La aplicación móvil necesita el mismo cuerpo del artículo, imagen principal, nombre del autor y temas relacionados. JSON:API puede exponer esas entidades de Drupal sin obligar al equipo backend a inventar un lenguaje de API desde cero. Los recursos relacionados pueden incrustarse mediante includes, y las colecciones pueden filtrarse o paginarse.

¿Es bonito el payload? A veces. A veces parece diseñado por un comité después de una comida larga.

Pero ese también es el punto. JSON:API es una especificación, no el gusto personal de un desarrollador. El sitio oficial de JSON:API lo describe como una especificación para construir APIs en JSON, con convenciones compartidas que reducen las discusiones sobre la forma de las respuestas y ayudan a los equipos a usar herramientas generales. Su tipo de medio es application/vnd.api+json, y la versión 1.1 se finalizó el 30 de septiembre de 2022.

Aquí hay un beneficio de gestión oculto. Un formato de respuesta estandarizado significa que el onboarding depende menos del conocimiento tribal. Un nuevo desarrollador frontend quizá siga maldiciendo la estructura anidada de data, attributes y relationships. Bien. Al menos está maldiciendo algo documentado.

La trampa que nadie quiere mencionar

JSON:API expone el modelo de contenido de Drupal de forma bastante directa. Eso puede ser una fortaleza, especialmente cuando Drupal es la fuente editorial de verdad. También puede filtrar demasiado de la forma interna de Drupal hacia el frontend.

Si tu modelo de contenido está limpio, JSON:API se siente eficiente. Si tu modelo de contenido es un museo de viejos compromisos, JSON:API hace visible el desorden.

He visto tipos de contenido “Article” con campos como field_new_body_2021, field_mobile_summary, field_legacy_related y field_do_not_use. JSON:API no convierte mágicamente eso en una API de producto elegante. Expone el modelo que realmente tienes. Un poco cruel, quizá. Pero útil.

La documentación de Drupal también deja claro un límite: JSON:API gestiona CRUD orientado a entidades, pero las reglas de negocio como inicio de sesión, restablecimiento de contraseña y creación de cuentas están fuera del trabajo de JSON:API. Si tu aplicación necesita acciones de dominio como “aprobar proveedor”, “calcular presupuesto de renovación” o “enviar reclamación”, no fuerces eso dentro de endpoints de entidades de contenido solo porque el módulo sea conveniente.

Ese camino se vuelve feo rápidamente.

GraphQL parece elegante porque mueve el dolor

GraphQL es seductor. El frontend pide exactamente los campos que quiere. La respuesta tiene la misma forma que la consulta. Tiene un esquema tipado. Parece diseñado para frontends basados en componentes porque, francamente, lo fue. El sitio oficial de GraphQL describe GraphQL como un lenguaje de consulta open source y un runtime del lado del servidor para APIs con un esquema fuertemente tipado, y muestra al cliente solicitando campos seleccionados en lugar de recibir una respuesta fija del servidor.

Para los equipos frontend, eso es una mejora real.

Piensa en una página de inicio compuesta por componentes: hero, artículos destacados, eventos, espacios de patrocinadores, navegación, alertas regionales. Con REST, el frontend puede llamar a varios endpoints. Con JSON:API, puede solicitar una colección e incluir recursos relacionados, pero la estructura sigue las relaciones entre entidades. Con GraphQL, la consulta puede parecerse más a la pantalla. Eso importa cuando los equipos lanzan superficies de producto rápidamente.

El módulo GraphQL de Drupal permite a los desarrolladores crear y exponer un esquema GraphQL para Drupal 10 y 11. Está construido sobre webonyx/graphql-php, admite la especificación oficial de GraphQL, incluye GraphiQL en /graphql/explorer y ofrece a los desarrolladores plugins productores de datos además de código personalizado para el trabajo de esquema.

Lee la redacción con atención: “crear y exponer”.

El módulo GraphQL actual de Drupal no es un espejo mágico que simplemente refleje cada campo de Drupal en una API ordenada. Drupal.org dice que la versión anterior 3.x generaba automáticamente un esquema a partir de entidades de Drupal y exponía detalles de Drupal mediante la API, mientras que la 4.x deja el diseño del esquema al desarrollador para que los detalles internos de Drupal puedan ocultarse. La misma página dice que la 4.x requiere que el desarrollador configure y mapee el esquema.

Eso no es una nota al pie. Es la factura.

GraphQL puede darte un contrato limpio entre el producto y el almacenamiento de contenido. Pero alguien tiene que diseñar ese contrato. Alguien tiene que mantenerlo cuando los editores agregan campos, cuando cambia el sistema de diseño, cuando llega la personalización, cuando legal pide lógica de consentimiento regional, cuando el equipo móvil necesita sincronización offline.

En realidad, eso es demasiado amable. Alguien tiene que ser dueño de ello. La propiedad es la línea presupuestaria que falta en muchas propuestas de GraphQL.

Cuándo GraphQL vale el coste

GraphQL tiene sentido cuando la API es un producto por derecho propio.

Una gran universidad con decenas de micrositios, una aplicación móvil para estudiantes, señalización digital, perfiles de profesores, catálogos de cursos y un sistema de diseño puede beneficiarse de una capa GraphQL. Los consumidores son variados. El grafo de contenido es profundo. Los equipos frontend necesitan acceso selectivo. La organización puede querer un contrato de API que oculte las excentricidades de los bundles de Drupal.

GraphQL también encaja cuando Drupal es solo una fuente entre varias. Tal vez el contenido venga de Drupal, los precios de un ERP, la disponibilidad de un motor de reservas y los derechos de usuario de un CRM. GraphQL puede presentar un esquema coherente a los clientes mientras los resolvers obtienen datos de distintos sistemas. El modelo de GraphQL se construyó alrededor de un esquema fuertemente tipado y una forma de respuesta especificada por el cliente, que es exactamente la razón por la que funciona bien en este tipo de capa de composición.

Pero ¿para un sitio de marketing normal con un frontend headless? Yo sería escéptico. Incluso un poco molesto.

Si la necesidad real es “React debería leer artículos de Drupal”, GraphQL puede ser una fiesta de disfraces. Gastarás dinero de arquitectura para evitar aprender includes y filtros de JSON:API. Peor aún, quizá crees una capa de API a medida que solo dos desarrolladores entienden.

La página del proyecto GraphQL de Drupal informa que las versiones estables están cubiertas por la política de avisos de seguridad de Drupal y enumera lanzamientos recientes para Drupal 10 y 11, incluido 8.x-4.14 publicado el 29 de abril de 2026 y una beta 5.0.0 para Drupal 10.4 y 11. Eso es saludable. No elimina el trabajo de diseño.

Un módulo contribuido puede ser maduro y aun así ser el valor predeterminado equivocado.

RESTful Web Services: antiguo, útil y normalmente sobreutilizado

REST se ha convertido en una de esas palabras que significa lo que el hablante necesite que signifique. A veces significa HTTP limpio orientado a recursos. A veces significa “devolvemos JSON desde un controller”. A veces significa “el proveedor nos dio un endpoint y un PDF”.

La tesis de Roy Fielding introdujo REST como un estilo arquitectónico para sistemas hipermedia distribuidos, con restricciones como separación cliente-servidor, comunicación sin estado, caché, una interfaz uniforme, sistemas en capas y código bajo demanda opcional. Esa idea original es más estricta que mucho de lo que se llama REST en los planes de proyecto.

El módulo RESTful Web Services de Drupal es útil porque puede exponer recursos con métodos específicos, formatos de serialización y autenticación. El material de estudio de Drupal describe recursos REST para entidades, soporte para métodos como GET, POST, PATCH y DELETE, serialización JSON o XML, y autenticación mediante Basic Auth, cookies u otros módulos como OAuth. También señala que los métodos no seguros requieren una cabecera de solicitud X-CSRF-Token.

Esto hace que REST sea bueno para trabajos de integración acotados.

Un proveedor de pagos publica el estado de una transacción en Drupal. Un sistema de almacén obtiene una lista de manuales de producto actualizados. Un portal de partners necesita un endpoint cuidadosamente diseñado para activos aprobados. Una aplicación móvil legacy ya espera /api/v1/articles/{id} y no puede reescribirse este trimestre.

REST te da control. También te da síndrome de página en blanco.

A diferencia de JSON:API, donde las convenciones ya están elegidas, un endpoint REST personalizado necesita decisiones: forma de la URL, formato de respuesta, formato de error, estilo de paginación, sintaxis de filtrado, versionado, autenticación, cabeceras de caché, documentación, política de deprecación. OpenAPI puede ayudar a documentar esa superficie, y la Especificación OpenAPI es una forma estándar e independiente del lenguaje de describir APIs HTTP para que humanos y máquinas puedan entenderlas sin leer código fuente.

Aun así, tienes que tomar las decisiones.

Y esas decisiones se quedan. Un endpoint descuidado diseñado en la segunda semana puede perseguir al producto durante años porque alguna versión de la app en circulación todavía depende de él.

La decisión no es “¿qué API es la mejor?”

Ese planteamiento es perezoso. Lo siento, pero lo es.

La mejor pregunta es: ¿qué tipo de acoplamiento puede permitirse tu organización?

JSON:API acopla a los consumidores al modelo de entidades de Drupal. Eso suele ser aceptable cuando Drupal es el sistema principal de contenido y el frontend es una capa de presentación de reemplazo. La recompensa es velocidad y menos invención backend.

GraphQL acopla a los consumidores a un esquema diseñado por tu equipo. Bien hecho, ese esquema oculta Drupal y expresa el dominio del producto. Mal hecho, se convierte en un segundo modelo de CMS mantenido en código.

REST acopla a los consumidores a endpoints personalizados. Eso es excelente para integraciones específicas y peligroso para la entrega amplia de contenido, porque cada endpoint se convierte en un producto en miniatura con su propia cola de mantenimiento.

Esta es la versión que pondría delante de un comité ejecutivo de dirección.

Las tablas son un poco estériles, pero esta ahorra reuniones.

Qué deberían vigilar los project managers

La elección de la API cambia el plan del proyecto más de lo que la gente admite.

Con JSON:API, la ruta crítica es el modelado de contenido. Si el modelo de contenido está bien pensado, el trabajo de API puede avanzar rápido. Si el modelo de contenido es caótico, el desarrollo frontend se ralentiza porque cada consulta expone otro compromiso editorial. Pon atención senior en la nomenclatura de campos, patrones reutilizables de paragraphs, relaciones de medios, taxonomía y permisos antes de que el equipo frontend empiece a cablear páginas.

Con GraphQL, la ruta crítica es la propiedad del esquema. ¿Quién diseña el esquema? ¿Quién revisa los cambios incompatibles? ¿Quién escribe los resolvers? ¿Quién gestiona problemas de rendimiento como consultas anidadas que disparan demasiadas cargas backend? El módulo GraphQL de Drupal proporciona herramientas y puntos de extensión, incluidos plugins productores de datos y GraphiQL, pero no elimina la necesidad de disciplina de ingeniería backend.

Con REST, la ruta crítica es la disciplina del contrato. Cada endpoint necesita documentación, pruebas, reglas de autenticación, semántica de errores y una historia de versionado. REST parece barato cuando se construye el primer endpoint. El quinto endpoint dice la verdad.

Una cosa más. La autenticación suele subestimarse. Drupal JSON:API está vinculado a los sistemas de autenticación y autorización de Drupal, y REST puede usar proveedores de autenticación como Basic Auth y cookies, con OAuth añadido comúnmente mediante módulos contribuidos. La documentación de Lupus Decoupled Drupal apunta a Simple OAuth como una forma de autenticar solicitudes API mediante token en configuraciones desacopladas.

No dejes eso para el sprint anterior al lanzamiento. Ese sprint ya está maldito.

Rendimiento: el argumento que todo el mundo simplifica

Los fans de GraphQL dicen que evita el over-fetching. Cierto. Los fans de JSON:API dicen que los includes reducen los viajes de ida y vuelta. También cierto. Los fans de REST dicen que la caché HTTP es directa. Cierto otra vez.

Ahora viene la parte desagradable: los tres pueden ser rápidos, y los tres pueden ser lentos.

GraphQL puede reducir el tamaño del payload, pero las consultas anidadas complejas pueden castigar al backend si los resolvers son descuidados. JSON:API puede usar la caché de respuestas de Drupal e includes, pero los payloads pueden ser verbosos. REST puede mapearse limpiamente a la caché HTTP, pero los endpoints personalizados a menudo olvidan la cacheabilidad hasta que empiezan las pruebas de rendimiento. Las restricciones REST de Fielding incluyen la caché porque la caché puede reducir el tráfico de red y la latencia, pero los datos obsoletos y la invalidación de caché siguen siendo compromisos reales. La documentación de JSON:API de Drupal vincula explícitamente el módulo con la caché de respuestas de Drupal, mientras que el módulo GraphQL está categorizado en Drupal.org bajo Desacoplado, Herramientas para desarrolladores y Rendimiento.

Así que no, GraphQL no es automáticamente la “opción de rendimiento”.

La primera mejora de rendimiento suele ser un mejor modelado de contenido. La segunda es la estrategia de caché. La tercera es evitar comportamientos tontos del cliente, como llamar al mismo endpoint doce veces porque nadie escribió una capa de acceso a datos.

¿Glamuroso? No. ¿Efectivo? Sí.

Un marco de selección directo

Si estuviera asesorando a un fundador o CTO, empezaría con esta secuencia.

Primero, usa las páginas renderizadas normales de Drupal salvo que tengas una razón para desacoplar. El desacoplamiento añade complejidad de hosting, preview, routing, caché, despliegue, autenticación y depuración. La propia documentación desacoplada de Drupal separa Drupal estándar de Drupal desacoplado señalando que el layout se mueve al frontend y el backend expone contenido mediante APIs. Ese cambio no es gratis.

Segundo, si te estás desacoplando principalmente por un frontend moderno, empieza con JSON:API. Construye una página real, no una demo. Incluye medios, menús o navegación, contenido relacionado, necesidades de preview, autenticación si hace falta y comportamiento de caché. Aprenderás más de una página fea que de seis diagramas de arquitectura.

Tercero, pasa a GraphQL solo cuando la experiencia del consumidor justifique el trabajo de esquema. Buenas razones incluyen múltiples consumidores frontend, la necesidad de ocultar detalles internos de Drupal, grafos de contenido complejos o agregación entre sistemas. Malas razones incluyen “a nuestro desarrollador frontend le gusta Apollo” y “el pitch deck para inversores dice GraphQL”.

Cuarto, usa REST para integraciones que necesiten límites estrictos. Un endpoint personalizado para una exportación a un partner puede ser limpio. Una plataforma de contenido entera hecha de endpoints artesanales puede convertirse en un cajón lleno de llaves sin etiqueta.

Y limpia el modelo de Drupal. Por favor. Ninguna capa de API puede rescatar completamente un modelo de contenido que nadie posee.

La política de lo “future-proof”

A los ejecutivos les gusta la frase “future-proof”. Entiendo por qué. Nadie quiere aprobar la reconstrucción de un backend y oír, dieciocho meses después, que la API elegida arrinconó a la empresa.

Pero prepararse para el futuro suele tener menos que ver con elegir la API más llamativa y más con decidir dónde se permite que ocurra el cambio.

JSON:API dice: “El modelo de Drupal es el contrato”. Eso es honesto y rápido.

GraphQL dice: “Nuestro esquema de producto es el contrato”. Eso es potente y caro.

REST dice: “Este endpoint es el contrato”. Eso es preciso y fácil de multiplicar hasta convertirse en un problema de mantenimiento.

No hay un ganador universal. Solo hay ajuste.

Mi sesgo es simple: empieza con lo menos personalizado que pueda sostener el producto. En Drupal, eso normalmente significa JSON:API. Añade GraphQL cuando puedas nombrar al propietario y el presupuesto. Añade REST cuando la integración sea lo bastante específica como para merecer su propia puerta.

La peor elección es la que se toma por moda, porque la moda nunca aparece para el mantenimiento.

¿Buscas la empresa de desarrollo Drupal #1 del mercado? Acabas de encontrarla.

Somos la mejor agencia digital especializada en Drupal, creada para entregar plataformas rápidas, seguras y escalables, sin concesiones. Desde nuevos desarrollos y rediseños hasta migraciones y soporte a largo plazo, nuestros expertos en Drupal entregan resultados de nivel empresarial con atención de nivel boutique.

Agenda una llamada hoy y convirtamos tu roadmap de Drupal en una realidad de alto rendimiento.