themeless

Simple RESTful API for Headless Drupal. Mainly intended to provide clean HTML content for use in an iFrame elsewhere, but apart from HTML, JSON and XML formats are also available out of the box for other use cases.

The RESTful API makes clean, themeless Drupal entities (nodes, users, taxonomy terms) available in multiple formats without a theme wrapper. Perfect for iframe embedding, headless Drupal, mobile apps, and external site integrations.

Key Features

• RESTful endpoints: Clean URLs like
  /api/node/{id},
  /api/user/{id},
  /api/taxonomy/term/{id}
• Multi-format output: JSON, XML, and HTML via
  ?format=
  query parameter
• Multi-entity support: Nodes, users, and taxonomy terms through unified API
• CORS support: Configurable cross-origin resource sharing for external integration
• View mode integration: Uses standard Drupal display management for field customization
• Security features: Domain whitelist and referrer checking
• Modern architecture: Service-based design with dependency injection
• Demo submodule:
  themeless_demo
  included with sample content for testing

Example URLs

# JSON output (default)
curl https://example.com/api/node/1
curl https://example.com/api/node/1?format=json

# XML output
curl https://example.com/api/node/1?format=xml

# HTML output (no theme wrapper)
curl https://example.com/api/node/1?format=html

# User entity
curl https://example.com/api/user/1?format=json

# Taxonomy term
curl https://example.com/api/taxonomy/term/5?format=json

Format Support

• JSON: Pretty-printed for readability, includes full entity data
• XML: Valid XML with entity fields as elements
• HTML: Rendered entity using Drupal's view builder and theme templates

Breaking Changes from 7.x-1.x (Drupal 7)

Version 2.0.0 is a complete rewrite for Drupal 10/11.
Migration from Drupal 7 requires a fresh install—there is no upgrade path.

• URL structure changed: From
  node/%/themeless
  to
  /api/node/{id}
  (RESTful)
• Configuration incompatible: Drupal 7 variables do not carry over; use new YAML configuration
• Format selection changed: From per-bundle configuration to query parameters
• Field display changed: From custom settings forms to native Drupal view modes
• Path aliases removed: Simple API, no
  /alias/themeless
  pattern support
• Permissions simplified: No custom "view themeless tab" permission (standard entity access applies)
• Requires PHP 8.1+: Minimum PHP version increased for modern Drupal

Requirements

Version Drupal Core PHP Branch Status 2.x ^10 || ^11 8.1+ 2.0.x Active development 1.x ^8 || ^9 7.4+ 1.0.x Maintenance only

Both branches have identical functionality and API. The only differences are PHP syntax compatibility (1.0.x uses PHP 7.4+ compatible syntax). Both branches receive security updates and critical bug fixes.

Requirements for all versions: Drupal Node module (core)

Configuration

Themeless uses configuration-as-code:
Module settings are managed through YAML configuration files, not admin forms. This ensures consistency across environments and version control compatibility.

Standard Drupal Admin UI

• Permissions
  (/admin/people/permissions): Grant "Access Themeless API" permission to roles
• View modes
  (/admin/structure/types/manage/[type]/display): Enable and configure "Themeless" display for entity types
• Field display
  (/admin/structure/types/manage/[type]/display/themeless): Choose fields and formatters to expose

Module Settings (YAML Files)

Edit
config/install/themeless.settings.yml
for:

• CORS configuration: Allowed origins and HTTP methods
• Domain whitelist: Restrict API access by referrer domain
• Access tokens: Secure token-based access for iframe embedding
• Security settings: Referrer checking and validation options

Deploy configuration changes via
drush config:export
and
drush config:import.

Security

• Respects standard Drupal entity access control (node view permissions, user visibility, etc.)
• CORS domain whitelist prevents unauthorized cross-domain requests
• Referrer checking optional for additional validation
• No bypass of core permissions system

Demo Submodule

The included
themeless_demo
module provides sample content for testing and development. Enable it to:

• Create demo nodes with various field types
• See example API responses
• Test format selection and view modes
• Verify CORS and security settings

Use Cases

• Embed Drupal content in external websites via iframe with clean HTML
• Build mobile apps using Drupal as a content backend in JSON
• Integrate Drupal data with third-party services
• Decouple frontend from Drupal theme system
• Create headless Drupal architectures

Version and Branch Strategy

• 2.x branch
  (current): Drupal 10/11, active development
• 1.x branch
  (planned): Drupal 8/9, maintenance mode
• 7.x-1.x branch
  (legacy): Drupal 7 only, no further development

Resources

• README: Installation and setup
• ANALYTICS: Integration with analytics services
• Demo module: References implementation in
  themeless_demo