APIs REST GraphQL Drupal Integraciones

Por qué Drupal encaja tan bien como núcleo de un ecosistema de APIs

Hace años que Drupal dejó de ser solo un CMS. Hoy es una plataforma de contenido estructurado con APIs de primer nivel en el core, y esa es la razón por la que tantos arquitectos lo eligen para mover datos entre sistemas. Si te planteas cómo crear un ecosistema de APIs REST y GraphQL con Drupal para integraciones empresariales, empieza entendiendo qué te da la herramienta de serie.

Desde Drupal 8, el core trae REST y JSON:API listos para usar. Cualquier nodo, taxonomía o usuario que modeles queda disponible para que lo consuma una app móvil, un ERP o un dashboard interno, sin escribir un solo controlador.

Cuando tu empresa necesita que la web hable con SAP, con HubSpot, con una app nativa y con un panel de BI, Drupal pasa a ser el sitio donde vive el contenido y desde el que se reparte. Adiós a tener la misma ficha de producto duplicada en cuatro sistemas.

Lo que viene de serie: REST en el core

Drupal incluye el módulo RESTful Web Services en el núcleo. Te permite exponer entidades (nodos, usuarios, términos de taxonomía, bloques) como recursos HTTP estándar.

Activación y endpoints

Con un drush en rest serialization tienes los módulos listos. A partir de ahí, Drupal sirve endpoints predecibles: /node/{id}?_format=json para un nodo, /entity/taxonomy_term/{id}?_format=json para taxonomías.

¿La pega? El REST del core se queda corto en filtros complejos o documentación automática. Para algo más serio acabas saltando al siguiente módulo.

JSON:API: el estándar que de verdad usas en producción

Desde la versión 8.7, el core incluye JSON:API. Implementa la especificación de jsonapi.org y, en la práctica, es lo que querrás usar el 90% de las veces en proyectos Drupal modernos.

Por qué supera al REST clásico

JSON:API te da filtrado avanzado, paginación estandarizada y sparse fieldsets (pedir solo los campos que necesitas). Elimina el clásico problema N+1 al permitir traer entidades relacionadas en una sola petición. Las URLs siguen un patrón estable, del estilo /jsonapi/node/article?filter[status]=1&sort=-created. Una vez que el equipo se acostumbra, todo funciona prácticamente solo.

Relaciones e includes

Quieres un artículo con su imagen destacada y el autor. Una llamada a /jsonapi/node/article/{uuid}?include=field_image,uid te devuelve todo en la misma respuesta. En una pantalla con datos de varias entidades, eso reduce decenas de llamadas a una. Los filtros admiten operadores lógicos desde la URL, lo cual ahorra código en el cliente.

GraphQL: cuando necesitas flexibilidad de verdad

GraphQL nació en Facebook como respuesta a un problema concreto: los clientes querían pedir exactamente los datos que iban a pintar, ni un campo más. En Drupal, el módulo graphql te da esa capacidad.

¿Cuándo merece la pena?

GraphQL brilla cuando tienes consumidores muy distintos pegando a la misma API. La app móvil quiere campos mínimos para no gastar batería, el dashboard interno necesita el modelo entero, y la web pública pide algo intermedio. Con REST acabas creando endpoints a medida o forzando over-fetching. Con GraphQL cada cliente pide lo suyo.

También es la opción natural si necesitas suscripciones en tiempo real o si manejas relaciones profundas (categorías anidadas, jerarquías de equipos, árboles de productos).

El módulo GraphQL desde la 4.x

Desde la rama 4.x, el módulo apuesta por un enfoque schema-first. Tú defines el schema en archivos .graphqls con SDL y solo expones lo que decides exponer. Las queries leen, las mutations escriben, y puedes meter validación y lógica de negocio antes de que nada toque la base de datos. Eso te da mucho más control que dejar el schema abierto por defecto.

REST o GraphQL: cómo elegir sin equivocarte

Spoiler: no es una decisión excluyente. Puedes (y a menudo debes) ofrecer ambos en la misma instalación de Drupal. Ahora bien, conviene saber cuándo pesa más uno u otro.

Tira de JSON:API si...

Tu API la van a consumir clientes con necesidades parecidas, quieres algo que funcione el primer día sin configuración, te interesa aprovechar caching HTTP estándar (Varnish, CDN, lo que sea), tus recursos siguen un patrón CRUD limpio o prefieres no depender de módulos contrib para algo crítico.

Tira de GraphQL si...

Tus consumidores piden datos muy distintos entre sí, el ancho de banda importa (móviles, países con conectividad mala), el modelo tiene relaciones complejas, tu equipo frontend domina la herramienta o necesitas suscripciones.

En proyectos grandes lo habitual es JSON:API para el grueso y GraphQL para una o dos integraciones que lo justifican.

Autenticación y autorización: lo que no puedes dejar para luego

Una API que expone datos empresariales sin autenticación seria es una bomba de relojería. Hay que pensarlo antes de abrir el primer endpoint.

OAuth 2.0 con Simple OAuth

Simple OAuth implementa OAuth 2.0 en Drupal con soporte para Authorization Code, Client Credentials y Password Grant. Generas las claves RSA, registras consumers con sus roles y scopes, y los tokens se refrescan solos. Es el estándar al que deberías ir por defecto en cualquier integración empresarial seria.

API Keys y JWT

Para integraciones internas más sencillas (un cron que mueve datos entre dos sistemas tuyos), Key Auth con claves en headers cumple. Y si tu plataforma ya circula JWT entre microservicios, el módulo JWT Authentication encaja sin fricciones.

Rate limiting y protección

Exponer APIs sin límites es invitar al abuso. Implementa rate limiting por IP o por consumer OAuth para controlar peticiones por minuto. El módulo Rate Limiter te lo permite configurar con bastante granularidad.

Todo input debe validarse a conciencia. Drupal aplica validaciones de campo de forma automática, pero para reglas de negocio más finas tendrás que escribir validadores propios. Y no descuides los detalles: CORS restrictivo, protección contra enumeración de IDs y mensajes de error que no chiven el stack interno. Una API verbosa cuando falla es un regalo para cualquier atacante con paciencia.

Conectar con el resto del stack empresarial

Aquí es donde un ecosistema de APIs deja de ser una abstracción y empieza a pagar facturas.

ERP y CRM

Conecta Drupal con SAP, Microsoft Dynamics u Odoo para sincronizar catálogos, precios, stock y pedidos. Drupal puede ser la capa de presentación que consulta el ERP en tiempo real, o trabajar con sincronizaciones programadas si el ERP no aguanta el tráfico web.

Con el CRM (Salesforce, HubSpot, Pipedrive) la integración suele ser bidireccional: los formularios crean leads y el historial del cliente alimenta la personalización en la web. Si un usuario logueado lleva el tag de "cliente premium", le sirves contenido distinto.

Marketing automation

Mailchimp, ActiveCampaign o Marketo se enchufan vía API para que eventos de comportamiento (una descarga, una visita repetida a la página de precios, un formulario de demo) disparen automatizaciones. Drupal envía los eventos y la herramienta decide qué secuencia activa.

Webhooks: cuando la API no espera

Hasta ahora hablamos de APIs que responden cuando alguien las llama. Pero hay un patrón complementario que importa tanto o más: Drupal avisando a otros sistemas cuando pasa algo. Con el módulo Webhooks o event subscribers a medida, notificas URLs externas cuando se publica contenido, se actualiza un usuario o se cierra un pedido.

Para procesos que no necesitan respuesta inmediata, encola los eventos con la Queue API de Drupal o un broker externo como RabbitMQ. Evitas que un sistema lento bloquee al usuario y abres la puerta a arquitecturas event-driven serias.

Documentación: el contrato que nadie escribe a tiempo

Una API sin documentación decente se consume mal. El módulo OpenAPI genera especificaciones OpenAPI 3.0 desde tus endpoints JSON:API y REST. Pasas esa spec a Swagger UI y tienes documentación interactiva donde se prueban llamadas desde el navegador.

Trátala como un contrato: URL estable, versionada junto al código, y aviso a los consumidores antes de cambiar nada. Una API bien documentada baja el coste de onboarding de semanas a horas.

Versionado de APIs

Las APIs empresariales evolucionan. Tu estrategia de versionado tiene que permitir cambios sin romper a quien ya integró contigo. Las tres vías clásicas son por URL (/api/v1/, /api/v2/), por header (Accept: application/vnd.api+json;version=2) o por parámetro de consulta. JSON:API en Drupal no trae versionado nativo, así que tendrás que montarlo con routing custom o un reverse proxy delante.

Define una política de deprecación clara antes de que la necesites. La práctica habitual es mantener N-1 (la versión actual y la anterior) con al menos seis meses de aviso antes de retirar nada. Comunícalo por email, por headers de deprecation y en la propia documentación.

Rendimiento bajo carga

Las APIs con tráfico real necesitan optimización seria. Configura cache HTTP con headers correctos (Cache-Control, ETag, Last-Modified) para que las respuestas estables se sirvan desde Varnish o CDN sin tocar Drupal. Esa sola medida puede dividir tu carga por diez.

Educa a los consumidores para que usen sparse fieldsets y pidan solo lo que pintan. Y en colecciones grandes, paginación por cursor en lugar de offset: el rendimiento se mantiene constante aunque la colección crezca a millones de registros.

Monitorización: lo que no mides, no controlas

Mide peticiones por endpoint, tiempos en p50/p95/p99, tasas de error y patrones raros. New Relic, Datadog o Grafana con Prometheus son las opciones cómodas. Para algo más austero, los logs del servidor web pasados por ELK o Loki te llevan lejos.

Tres escenarios reales

Para aterrizar todo esto, así se combinan las piezas en proyectos típicos de empresas españolas.

Portal corporativo multicanal: JSON:API sirve contenido a la web, a una app móvil nativa y a pantallas en oficinas. Cada canal pide los campos que necesita y los editores trabajan en una sola interfaz.

Ecommerce sincronizado: el ERP empuja catálogo y stock vía API, la ficha de producto consulta precios en tiempo real y los pedidos viajan a logística por webhook en cuanto se confirma la compra.

Intranet conectada: Drupal consume APIs de RRHH para el directorio, del sistema de reservas para salas y del calendario corporativo para eventos. Y a la vez expone su propia API para que el chatbot interno responda preguntas sobre políticas publicadas como contenido estructurado.

Si necesitas diseñar e implementar todo esto sin tropezar con los errores típicos, ponte en contacto con nuestro equipo de arquitectura Drupal y diseñamos juntos la estrategia de integración que tu empresa necesita.

Lo que te llevas

Construir un ecosistema de APIs con Drupal convierte tu web en el centro neurálgico del stack, no en una isla más. JSON:API resuelve el caso estándar y GraphQL cubre la flexibilidad de los proyectos con consumidores heterogéneos. La combinación es lo que hace fuerte la propuesta.

El secreto: pensar a largo plazo desde el día uno. Autenticación robusta, documentación como contrato, versionado planificado y monitorización que te deje evolucionar con tranquilidad. Las empresas que dominan sus APIs dominan su flujo de información, y eso se nota en la cuenta de resultados antes de lo que parece.