Directus is an open source headless CMS that sits directly on top of any SQL database, automatically generating real-time REST and GraphQL APIs based on the existing schema. It allows teams to manage structured content through a flexible admin interface without enforcing a proprietary data model, supports granular permissions, and can be deployed as a Node.js application in any environment.

Architecture

Directus connects directly to any SQL database, automatically generating REST and GraphQL APIs that reflect the existing schema. It does not modify your tables unless explicitly configured, preserving your data model. All content and structure remain accessible both through Directus and direct SQL queries.

Example: Database Table Structure

code
CREATE TABLE articles ( id SERIAL PRIMARY KEY, title VARCHAR(255),body TEXT,author_id INTEGER,published_at TIMESTAMP);

Content Modeling

Content modeling in Directus is handled by defining tables and fields directly in the SQL database, with each table representing a content type. Relationships such as one-to-many or many-to-many are established using standard foreign key constraints. Directus automatically detects these links and exposes them in its API and admin interface for relational data management.

For example, to associate articles with authors, you can add a foreign key constraint to the articles table:

Example: Defining a Relationship

code
ALTER TABLE articles ADD CONSTRAINT fk_author FOREIGN KEY (author_id) REFERENCES users(id);
Banner for CDN

API Access

Directus automatically generates REST and GraphQL APIs based on your SQL database schema. These APIs support filtering, sorting, pagination, and relational queries, providing real-time access to your data with consistent functionality across both API types.

Example: REST API Request

code
GET /items/articles?filter[author_id][_eq]=2&sort=-published_at Authorization: Bearer {ACCESS_TOKEN}

Example: GraphQL Query

code
query {articles(filter: { author_id: { _eq: 2 } }) {id title body published_at author {id name}}}

Authentication and Permissions

Directus supports multiple authentication methods, including JWT, OAuth2, and static tokens, with permissions managed through a granular, role-based system configurable at both the collection and field level. This ensures only authorized users can access or modify specific data, aligning access controls with organizational requirements.

Example: Role-Based Permission (JSON)

code
{"role": "editor","collection": "articles","permissions": {"read": true,"create": true,"update": true,"delete": false}}

Explanation:

  • The "editor" role for the "articles" collection has read, create, and update permissions enabled, but cannot delete records.
  • Permissions are enforced at the API and admin interface, ensuring users only see and act on data allowed by their assigned role.

Extensibility

Directus enables extensibility through custom API endpoints, event-driven webhooks, and modular extensions, allowing developers to automate workflows and integrate with external systems. Event hooks can trigger actions on specific content events, supporting advanced business logic and real-time integrations.

Example: Webhook Configuration (JSON)

code
{"event": "items.articles.create","url": "https://example.com/webhook","method": "POST"}

Explanation:

  • a webhook is configured to send a POST request to https://example.com/webhook whenever a new article is created.
  • This setup allows external services to respond automatically to content changes, such as triggering static site rebuilds or syncing data with other platforms.

Deployment

Directus is deployed as a Node.js application and can run on any server or container platform that supports Node.js, including Linux, Windows, and cloud environments. Using Docker Compose, you can quickly launch Directus by specifying the official image, mapping ports, and providing environment variables for your database connection.

Example: Docker Compose Deployment

code
services:directus:image: directus/directus:latest ports:- 8055:8055 environment: DB_CLIENT: postgres DB_HOST: db DB_PORT: 5432 DB_DATABASE: mydb DB_USER: user DB_PASSWORD: password

This configuration pulls the latest Directus image, connects it to a PostgreSQL database, and makes the Directus admin and API accessible on port 8055.

Use Cases

  • Headless Content Management: Manage and deliver content to websites, apps, and digital platforms using REST or GraphQL APIs, decoupling backend content from frontend presentation.
  • Data-Driven Applications: Integrate with existing SQL databases to power dashboards, analytics tools, or any application requiring complex, structured data management.
  • Custom Workflows and Automation: Implement content approval processes, versioning, scheduling, and event-driven automation using built-in hooks and webhooks.
  • Multi-Project and Omnichannel Delivery: Manage multiple brands or projects from a single instance and distribute content across various channels and devices.
  • Scalable Enterprise Solutions: Support large-scale deployments, such as enterprise e-commerce or media platforms, with granular permissions, flexible data modeling, and high performance.