Qué es Directus y cuáles son sus características

Actualizado el

16 de noviembre de 2025

a las

20:42

Directus es un headless CMS de código abierto desarrollado por Ben Haynes en 2004. Su principal característica es la capacidad de generar APIs de forma fácil e intuitiva.

Publicado el

14 de febrero de 2024

a las

17:15

Introducción

Un headless CMS es una herramienta que, al igual que un sistema de gestión de contenidos convencional, o por sus siglas en inglés, CMS (Content Management System), permite a los editores de contenido crear y gestionar información a través de una interfaz gráfica conectada a una o múltiples bases de datos de un sitio web o aplicación.

La diferencia entre una y otra es su enfoque práctico. La primera permite desacoplar la información y la forma en que se presenta al usuario final. Mientras que la segunda está vinculada a una plantilla, un ejemplo es WordPress.

Un headless CMS, además de acelerar el proceso de desarrollo en comparación a un Backend a medida, ofrece un grado de flexibilidad adicional, el equipo de desarrollo puede trabajar en paralelo en soluciones a medida e implementar soluciones temporales sin retrasar el desarrollo.

Qué es Directus

Directus es un headless CMS, o, en términos más técnicos, un BaaS de código abierto.

Fue desarrollado por Ben Haynes en 2004 y opera bajo la marca Monospace Inc. Empresa que ofrece una versión de pago y es la encargada de gestionar el servicio de forma integral.

Directus es mantenido por un equipo estable, además, cuenta con una comunidad que trabaja activamente en el mantenimiento de su código.

Esta herramienta es de código abierto y siguiendo las pautas de su documentación, casi cualquier persona puede contribuir en mejorar su código o añadir nuevas funcionalidades.

Más allá de las características estándar de otros headless CMS, Directus ofrece dos enfoques para consumir el API: GraphQL y REST.

De manera independiente al formato de elección o a la base de datos, no es necesario realizar ninguna configuración adicional.

A pesar de ello, se debe tener en cuenta que el acceso público está restringido de manera predeterminada.

Antes de empezar a trabajar con el API es necesario generar un token con el usuario administrador o en su defecto, configurar permisos públicos para cada colección que se desea exponer de manera explícita.

La forma más recomendable es utilizar un token, y evitar exponer las colecciones a visitantes con malas intenciones.

Además de estas características relacionadas a la API, Directus cuenta con una variedad de sistemas de bases de datos para elegir como: PostgresSQL, MySQL, OracleDB, MSSQL, SQLite3 o CockroachDB.

Características destacadas

Entre las características destacadas se encuentra la interfaz gráfica que resulta fácil e intuitiva incluso para nuevos usuarios.

Otra son los Flows, o en castellano, flujos. Esta es la manera en que se automatizan tareas o se procesa la información con Directus.

Existen distintos tipos, cada uno con un propósito diferente, aunque en general se utilizan para extender las funcionalidades de Directus o para hacer registros de actividad en la plataforma.

Interfaz Gráfica

La interfaz de usuario de Directus es flexible. Permite mostrar directorios a una categoría de usuarios con roles específicos. De la misma forma, ocultar colecciones a usuarios con un rol de editor de contenido, también limitar las acciones que los usuarios con distintos roles pueden ejecutar.

Dichas acciones van desde lo más básico cómo eventos CRUD hasta acciones más complejas como la creación de nuevas colecciones, Flows o incluso nuevos roles y permisos. Cada usuario puede personalizar la interfaz gráfica según su preferencia o idioma.

Permite importar y exportar la información de las colecciones en distintos formatos como JSON, CSV, XML o YAML.

Además de esto, es posible aplicar distintos filtros como, el máximo de registros a exportar, filtrado por campos como publicaciones por autor, de forma ascendente o descendente o incluso, por palabras clave.

Gestión de roles y usuarios

La gestión modular de roles de usuario reduce el riesgo de exponer información crítica del sistema. Esta característica hace que para trabajar con Directus no sea necesario contar con conocimientos avanzados de herramientas de gestión de contenidos.

Cualquier usuario con experiencia en sistemas de este tipo es capaz de utilizar Directus para crear, actualizar o eliminar contenido.

También es posible configurar roles y permisos personalizados para cada situación o tipo de usuario.

Event Hooks

Los Event Hooks son eventos que se activan con una interacción en una instancia de Directus, con una modificación en los datos de las colecciones o incluso errores.

Es posible configurar dos tipos: los bloqueantes, que detienen temporalmente otras acciones hasta que se completa, o los no bloqueantes, ideales para extender las funcionalidades de Directus, como eliminar elementos remanentes de relaciones M2A.

También es posible ajustar el Scope del Event Hook (acción que lo desencadena), como crear, actualizar o eliminar elementos, inicios de sesión, errores o cron jobs entre otras cosas.

La Documentación oficial ofrece una explicación más detallada sobre este tipo de flujos.

Captura de pantalla de la interfaz de Directus durante la creación de un Event Hook

Webhooks

Los Webhooks son una técnica para la comunicación en tiempo real entre aplicaciones, ideal para la automatización basada en eventos. Son esenciales en escenarios donde es necesario conocer el estado de una transacción en tiempo real, como el seguimiento del estado de una compra con una integración de Stripe.

Captura de pantalla de la interfaz de Directus durante la creación de un Webhook

Schedule (CRON)

Los Schedule (CRON) son demonios que se ejecutan a intervalos regulares, similares a los programadores de tareas en sistemas *nix o Windows. Son útiles para ejecutar tareas de forma programada y regular.

Captura de pantalla de la interfaz de Directus durante la creación de un Shedule (CRON)

Another Flow

Esta técnica implica desencadenar un Flow a través de otro. Es útil, por ejemplo, cuando un Event Hook falla en la eliminación de elementos relacionados a través de M2A.

Facilita el registro del fallo y la activación de otro Flow para notificar al equipo técnico.

Captura de pantalla de la interfaz de Directus durante la creación de un Another Flow

Manual

Este tipo de Flow se inicia manualmente desde la colección correspondiente, ideal para crear botones integrados para reportar fallos de forma sencilla y directa.

Velocidad de desarrollo

Desarrollar un backend personalizado requiere tiempo y recursos, es por eso que utilizar un headless CMS, como Directus, u otro que satisfaga las necesidades del proyecto, puede ser una solución rápida y económica.

Según los requisitos técnicos de la aplicación o sitio web a desarrollar, una solución personalizada implica trabajar en una interfaz de usuario desde el principio, que permita gestionar los distintos roles y acciones.

Que los administradores de una web puedan crear nuevos roles y gestionar los existentes implica manejar las relaciones de las tablas en la base de datos, así como los endpoints y esto puede resultar en trabajo tan agotador como costoso.

Además implica realizar pruebas exhaustivas para garantizar no solo el correcto funcionamiento del sistema, sino también su seguridad. Todo lo anterior es posible, pero tiene un precio: tiempo y recursos. Dos cosas que no siempre coinciden.

Entre las ventajas de utilizar un headless CMS como Directus, que además es de código abierto, es que ha sido puesto a prueba por miles de usuarios y desarrolladores en distintos escenarios.

Utilizar un sistema que cuenta con el respaldo de otros desarrolladores que quizá, tengan mucha más experiencia en otros campos genera cierta confianza y tranquilidad. Esta la magia del software libre o de código abierto.

Incluso con un headless CMS como BaaS, es posible escalar una aplicación y extender las funcionalidades a través de los microservicios.

Implementación flexible

La facilidad de implementación es otro punto a favor de un headless CMS como Directus. De acuerdo al contexto de cada proyecto, crear un Backend completamente personalizado es una tarea mesiánica y absurda cuando es recurrente, aunque menos cuando no lo es.

Según la experiencia previa con Directus y de la complejidad de los requisitos del proyecto, es posible tener una instancia up and running con distintas colecciones y relaciones entre las mismas, en como mucho, un día.

Esto se debe a que, como se mencionó anteriormente, Directus facilita consumir la información a través de REST o GraphQL.También modelar datos a través de una interfaz gráfica intuitiva, crear relaciones complejas en cuestión de minutos y gestionar los permisos con la misma facilidad.

Opciones para desplegar una instancia de Directus

Al igual que otras tecnologías, como por ejemplo Docker, Directus cuenta con diversas maneras para desplegar una instancia en local o producción.

Bien sea a través del SDK con NodeJS, con Docker o a través del servicio integral de Monospace Inc, Directus Cloud.

Directus Cloud

Este método es de pago y cuenta con las garantías de un equipo técnico especializado. Dado el caso que algo vaya mal, el soporte técnico está disponible 24/7.

Directus Cloud cuenta con actualizaciones periódicas de forma automática, lo que se traduce en un software siempre actualizado con la última versión disponible. Según el contexto de cada proyecto, puede o no merecer la inversión.

Servidor privado

El Self-Hosting (alojamiento propio), consiste en alojar uno o varios servicios en un servidor privado sin depender de servicios de terceros como VPS.

Esta opción permite una mayor flexibilidad y libertad, así mismo, si se invierte el tiempo y las medidas necesarias también incrementa la seguridad. Aunque todo lo anterior conlleva una serie de responsabilidades a considerar.

La forma más sencilla para desplegar Directus en un servidor privado es con una imagen de Docker. Esto significa que las actualizaciones y migraciones de una versión a otra y, en especial cuando son versiones con "Breaking Changes", quedan completamente delegadas al equipo técnico a cargo del proyecto.

Sin embargo, hospedar Directus en un servidor privado también tiene sus ventajas, tales como el control a un nivel más granular o entradas y consultas ilimitadas a la base de datos y el API.

Consideraciones importantes

Todo sistema tiene limitaciones y Directus no es la excepción. Sin embargo, en algunas situaciones las limitaciones dependen más del tipo de proyecto y de los requisitos del mismo.

Por esta razón, antes de iniciar un proyecto con esta herramienta, debe considerarse que aunque se trata de un proyecto maduro y con 20 años a las espaldas, tiene funcionalidades que apenas se han introducido en versiones recientes.

Ese es el caso del historial de versiones introducido en la versión 10.7.

Al crearse un nuevo elemento en una colección que permite versionado, hay relaciones cuyo valor no aparece en el delta, esto es así hasta que dicho elemento se crea y se guarda en la versión principal. Un ejemplo de este comportamiento son las relaciones M2O.

Otra limitación a considerar son los valores por defecto. Un ejemplo claro es un campo de tipo string con valor "x" por defecto. No se muestra dicho valor en el delta a no ser que se inserte un valor distinto al predeterminado de manera explícita.

La correcta visualización se ve dificultada por esta limitación. En especial la de los elementos donde, el renderizado depende de una condición que a su vez depende de un valor por defecto.

Estructura de las consultas

Las consultas a las colecciones de Directus pueden incluir relaciones anidadas como M2A, M2O o Translations.

Para acceder a ellas se hace a través de niveles, esto significa que, una relación anidada representa un nivel, y así mismo las relaciones subyacentes también.

El problema no surge con el formato de las consultas ni su estructura jerárquica, llega más bien con el diseño inicial de las colecciones y relaciones entre las mismas.

Una consulta a una colección con relaciones anidadas será tan larga y difícil de mantener como su nivel de profundidad.

El siguiente ejemplo muestra 3 niveles de profundidad: content es un campo de tipo M2A, una de las relaciones de content es image, esta a su vez tiene una relación de tipo Translations para campos como alt, title, entre otros. La consulta podría verse de la siguiente forma:

typescript

http://localhost:8055/items/posts?fields=*,translations.*,content.*,content.item.*,content.item.translations.*

Para ilustrar de manera más detallada, el próximo ejemplo muestra una consulta básica al artículo "Directus: qué es y qué ventajas ofrece" y expande sobre relaciones anidadas de manera más concisa.

typescript

http://localhost:8055/items/posts?fields=*,filter[translations][slug][_eq]=directus-que-es-y-cuales-son-sus-ventajas-frente-a-un-backend-personalizado

Sujeta a la estructura de la colección, la respuesta de la consulta podría ser similar al siguiente JSON:

json

{
    "data": [
        {
            "date_created": "2024-07-04T15:15:24.000Z",
            "date_updated": "2024-07-09T09:10:30.000Z",
            "cover": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "user_created": "xxx-xxxxx-xxx-xxx-xx",
            "translations": [
                929
            ],
            "content": [
                3913,
                3915,
                3916
            ]
        }
    ]
}

La respuesta incluye campos de tipo Array numérico, sin embargo no es posible acceder a los valores de esos campos sin antes expandir la profundidad de la consulta

typescript

http://localhost:8055/items/posts?fields=*,translations.*,content.*&filter[translations][slug][_eq]=directus-que-es-y-cuales-son-sus-ventajas-frente-a-un-backend-personalizado

json

{
    "data": [
        {
            "date_created": "2024-07-04T15:15:24.000Z",
            "date_updated": "2024-07-09T09:28:27.000Z",
            "cover": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "user_created": "xxx-xxxxx-xxx-xxx-xx",
            "translations": [
                {
                    "id": 929,
                    "posts_id": "x",
                    "languages_code": "es",
                    "title": "Directus: Qué es y Cuáles son sus Ventajas frente a un Backend Personalizado",
                    "slug": "directus-que-es-y-cuales-son-sus-ventajas-frente-a-un-backend-personalizado",
                    "summary": "<p>Directus. Una potente herramienta para crear y gestionar grandes cantidades de datos de forma f&aacute;cil e intuitiva. La principal caracter&iacute;stica de un headless CMS, en este caso, Directus, es que te permite presentar tus datos de la forma que m&aacute;s creas conveniente para tu web o aplicaci&oacute;n. Esto y otros aspectos m&aacute;s es de lo que os voy hablar hoy.</p>",
                    "author_pick": false,
                    "meta_description": null,
                    "status": "published"
                }
            ],
            "content": [
                {
                    "id": 3913,
                    "posts_id": "x",
                    "item": "x",
                    "collection": "table_of_contents",
                    "sort": "x"
                },
                {
                    "id": 3915,
                    "posts_id": "x",
                    "item": "x",
                    "collection": "title",
                    "sort": "x"
                },
                {
                    "id": 3916,
                    "posts_id": "x",
                    "item": "x",
                    "collection": "wysiwyg",
                    "sort": "x"
                }
            ]
        }
    ]
}

Aunque se ha expandido la profundidad de la consulta, aún no es posible acceder a todos los campos de las relaciones M2A.

Para ello es necesario expandir la profundidad y apuntar a las colecciones de cada una de las relaciones M2A, o las necesarias.

El próximo es un ejemplo acceder al contenido de la relación con los WYSIWYGS (what you see is what you get).

json

http://localhost:8055/items/posts?fields=*,translations.*,content.*, content.item.*, content.item.translations.*&filter[translations][slug][_eq]=directus-que-es-y-cuales-son-sus-ventajas-frente-a-un-backend-personalizado

json

{
    "data": [
        {
            "date_created": "2024-07-04T15:15:24.000Z",
            "date_updated": "2024-07-09T09:28:27.000Z",
            "cover": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "user_created": "xxx-xxxxx-xxx-xxx-xx",
            "translations": [
                {
                    "id": 929,
                    "posts_id": "x",
                    "languages_code": "es",
                    "title": "Directus: Qué es y Cuáles son sus Ventajas frente a un Backend Personalizado",
                    "slug": "directus-que-es-y-cuales-son-sus-ventajas-frente-a-un-backend-personalizado",
                    "summary": "<p>Directus. Una potente herramienta para crear y gestionar grandes cantidades de datos de forma f&aacute;cil e intuitiva. La principal caracter&iacute;stica de un headless CMS, en este caso, Directus, es que te permite presentar tus datos de la forma que m&aacute;s creas conveniente para tu web o aplicaci&oacute;n. Esto y otros aspectos m&aacute;s es de lo que os voy hablar hoy.</p>",
                    "author_pick": false,
                    "meta_description": null,
                    "status": "published"
                }
            ],
            "content": [
                {
                    "id": 3913,
                    "posts_id": "x",
                    "collection": "table_of_contents",
                    "sort": "x",
                    "item": {
                        "id": "x",
                        otros campos...
                        "content": [
                            753,
                            234,
                            249,
                            025,
                            786
                        ],
                        "translations": [
                            {
                                "id": "x",
                                "tables_of_contents_id": "x",
                                "languages_code": "es",
                                "title": "Tabla de contenidos"
                            }
                        ]
                    }
                },
                {
                    "id": 3915,
                    "posts_id": "x",
                    "collection": "title",
                    "sort": "x",
                    // otros campos...
                    "item": {
                        "translations": [
                            {
                                "id": "x",
                                "titles_id": "x",
                                "languages_code": "es",
                                "title": "Webhooks",
                                // otros campos...
                            }
                        ]
                    }
                },
                {
                    "id": 3916,
                    "posts_id": "x",
                    "collection": "wysiwygs",
                    "sort": "x",
                    "item": {
                        "id": "x",
                        "wysiwyg_code_name": "La consulta a la API generada por Directus podría considerarse como ambas:",
                        "text_align": null,
                        "max_width": "unset",
                        "margin_top": null,
                        "translations": [
                            {
                                "id": "x",
                                "wysiwygs_id": "x",
                                "languages_code": "es",
                                "wysiwyg": "<p>La consulta a la API generada por Directus podr&iacute;a considerarse como ambas: una ventaja y una desventaja. Veamos por qu&eacute; es una ventaja y cuando podr&iacute;a convertirse en lo contrario.</p>\n<p>Cuando creas una colecci&oacute;n en <strong>Directus&nbsp;</strong>puedes acceder a ella, siempre y cuando, tengas los permisos adecuados, a trav&eacute;s de <strong>REST</strong> o <strong>GraphQL. </strong>Ambas formas de consumir el API pueden resultar relativamente sencillo dependiendo de con qu&eacute; enfoque te sientas m&aacute;s c&oacute;modo, no tener que configurar ning&uacute;n endpoint ni tampoco tener que ajustar los permisos de acceso son un punto a favor, puesto que, para hacer una consulta tan solo necesitas generar un token de acceso desde el panel de usuario con el que est&eacute;s accediendo, el token generado te dar&aacute; acceso a todas las colecciones a las que tengas permiso para acceder, modificar o eliminar, bastante straight forward y sin complicaciones.</p>\n<p>Pero si lo anterior es todo ventajas... &iquest;Qu&eacute; podr&iacute;a ser tan negativo de todo esto? Esa misma flexibilidad para crear tus datos y acceder a ellos. Hay que tener en cuenta que no todas las aplicaciones tienen como requisito un simple crud con relaciones sencillas. En ocasiones las relaciones pueden ser bastante complejas, en especial las <strong>M2A</strong>, este tipo de relaciones se basa en relacionar un campo de tu colecci&oacute;n con otra que a su vez puede estar relacionada con otra colecci&oacute;n, y as&iacute; podemos seguir dependiendo de lo que estemos construyendo, para hacer este tipo de escenario m&aacute;s f&aacute;cil de entender, veamos un breve ejemplo.&nbsp;</p>\n<p>Una consulta b&aacute;sica a, por ejemplo, esta publicaci&oacute;n, tendr&iacute;a la siguiente estructura:&nbsp;</p>"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Es posible simplificar la consulta anterior accediendo a todos los campos, sin embargo, esto significa que la respuesta contiene todas las relaciones anidadas.

Esto puede resultar ineficiente si la intención es acceder solo al primer nivel o a unos campos en especifíco.

Documentación y soporte

La Documentación de Directus puede llegar a ser vaga, escasa o poco detallada, lo que hace que esta plataforma se perciba como complicada al primer contacto, aunque no es la norma.

Directus cuenta con una comunidad bastante activa en distintas plataformas como: GitHub, Discord o Youtube.

Además cuentan con un blog donde publican todas las novedades y nuevas funcionalidades.

La presencia en diversas plataformas hace que encontrar información sobre este headless CMS no sea una tarea difícil aunque sí un poco más laboriosa.

La mayor parte de los issues, como el problema del contenido remanente en colecciones M2A o deltas que no retornan valores por defecto, se encuentran registrados en GitHub y es fácil obtener una respuesta rápida a través de los distintos canales del servidor de Discord.

Gestión de contenido remanente en relaciones M2A

La eliminación en cascada es una funcionalidad donde al eliminar el elemento padre el hijo es eliminado de manera automática también.

En Directus, este comportamiento está limitado a las tablas intermedias que hacen posible la relación entre una colección y la otra, ese es el comportamiento esperado y correcto.

Sin embargo existen situaciones en las que se espera que al eliminar el elemento padre de una relación M2A también se elimine el hijo y que además se elimine el elemento de la colección original.

Cuando esto no pasa es cuando aparecen los elementos remanentes, por que Directus no gestiona su eliminación automática.

La solución para esto está relacionada con otra funcionalidad de Directus, los Flows y los microservicios.

Consiste en crear un flujo que detecta cuando un elemento ha sido eliminado de una relación M2A o M2O, esto activaría una llamada a un endpoint con el payload que contiene la información del elemento y su eliminación se gestionaría a través de un microservicio.

Nivel de dificultad

Para un editor de contenido con experiencia en herramientas como Strapi, Wordpress o Drupal, Directus puede ser relativamente sencillo de aprender a utilizar.

El equipo o la persona a cargo de la implementación debe tener en cuenta los distintos roles; administradores, desarrolladores, editores, editores invitados, o cualquier otro rol que el proyecto tenga como requisito.

Esta separación de responsabilidades facilita y disminuye la curva de aprendrizaje.

Unos roles bien definidos permiten que cuando un usuario configure algo en su perfil, este tendrá la certeza que solo estará modificando datos relacionados a su perfil.

Un ejemplo claro es cuando un editor invitado solo puede ver y editar las publicaciones que ha creado, un editor interno puede cambiar el estado de sus publicaciones o de editores invitados, pero nunca de otros editores internos. Y solo el administrador puede eliminar una publicación.

Una clara separación de responsabilidades facilita la curva de aprendizaje a usuarios poco técnicos. Para los perfiles técnicos la curva de aprendizaje es distinta, depende mucho del nivel de experiencia, tiempo y recursos disponibles.

Conclusión

Directus es una alternativa formidable en comparación a soluciones personalizadas, en especial para proyectos que requieren una velocidad de desarrollo considerable y herramientas probadas en producción listas para utilizar.

A pesar de ello, su uso no se limita al de un headless CMS. Gracias a que está separado en capas, es posible trabajar en soluciones personalizadas y más tarde desacoplar a esta última de Directus de manera gradual y segura.

La interfaz gráfica resulta fácil e intuitiva para usuarios tanto experimentados como sin experiencia previa, además, la posibilidad de personalizar la interfaz de gráfica a nivel de usuario brinda una mayor flexibilidad.