Transform API
A Drupal module that exposes routes and entities transformed to JSON with a comprehensive API, enabling Drupal developers to leverage their existing knowledge of entities, view modes, and templates to produce JSON instead of HTML.
transform_api
Install
composer require 'drupal/transform_api:^2.1'
Overview
Transform API provides a familiar path for Drupal developers to transform their knowledge of entities, view modes, and templates into JSON output instead of HTML. When accessing any route in Drupal with the format=json GET parameter, the request is rerouted through the Transform API, producing JSON output while retaining cacheability and permission requirements.
The module introduces key concepts analogous to Drupal core: Transforms (equivalent to theme templates), Transformer (equivalent to the renderer service), Transform arrays (equivalent to render arrays), Transform modes (equivalent to view modes), and Transform blocks (equivalent to blocks). These provide global JSON outputs segmented into configurable regions.
The module offers extensive plugin support for field transformations, supporting all common Drupal field types including text, boolean, integer, float, datetime, image, file, link, entity reference, and more. It integrates with Layout Builder and supports responsive images through submodules.
Features
- Automatic JSON transformation of any Drupal route by adding format=json parameter to URLs
- Transform modes for configuring how entities are transformed to JSON, similar to view modes for HTML
- Transform blocks system for adding global JSON data to responses, organized into configurable regions
- Comprehensive field transform plugins supporting all common Drupal field types (text, boolean, numeric, datetime, image, file, link, entity reference, etc.)
- Full caching support using Drupal's CacheableMetadata for optimal performance
- Multiple authentication methods including Basic Auth, Cookie, and OAuth2
- Alter hooks for customizing transformation output at various levels
- Layout Builder integration for transforming section components
- Nested transform support for composing complex JSON structures
- Lazy transformer callbacks for handling dynamic uncacheable content
Use Cases
Headless/Decoupled Drupal Setup
Use Transform API to serve JSON content to a JavaScript frontend framework (React, Vue, Angular). Configure transform modes for different display contexts (full, teaser, card) and let the frontend consume the structured JSON data while maintaining Drupal's content management capabilities.
Mobile Application Backend
Expose Drupal content as JSON APIs for native mobile applications. The API supports Basic Auth, Cookie, and OAuth2 authentication methods. Entity transforms provide structured data while transform blocks add global data like navigation menus and site configuration.
Content Syndication
Export content in JSON format for syndication to other systems. Use transform modes to control which fields are exposed and how they're formatted. The caching system ensures efficient delivery even under high load.
Progressive Web Application (PWA)
Build a PWA that fetches JSON from Transform API endpoints. Use region-based transform blocks to provide app shell data (menus, user info) separately from main content, enabling efficient caching strategies.
API-First Content Modeling
Design content types with API consumption in mind. Configure transform modes per bundle to expose different field sets for different consumers. Use alter hooks to add computed fields or modify output structure without changing content models.
Tips
- Add format=json to any Drupal URL to get JSON output instead of HTML
- Use transform modes like view modes - create 'card', 'teaser', 'full' transforms for different contexts
- Transform blocks are evaluated once and cached - use #lazy_transformer for dynamic uncacheable content
- Nest EntityTransform objects in transform arrays rather than calling transform() directly for better caching
- Use hook_ENTITYTYPE_transform_alter for entity-specific customizations instead of the generic hook_transform_alter
- The #collapse control key reduces nesting when an array has only one member - useful for single-value fields
- Transform block regions can be queried independently via the region parameter in RequestPathTransform
Technical Details
Admin Pages 7
/admin/structure/display-modes/transform
Lists all transform modes available in the system. Transform modes define how entities are transformed to JSON, similar to how view modes define HTML rendering. Users can add, edit, and delete transform modes for different entity types.
/admin/structure/display-modes/transform/add/{entity_type_id}
Create a new transform mode for a specific entity type. The transform mode defines how entities of this type will be transformed to JSON.
/admin/structure/block/transform
Manage transform blocks that provide global JSON data for all transformed routes. Blocks can be assigned to regions and configured with visibility conditions similar to regular Drupal blocks.
/admin/structure/block/transform/region
Manage transform block regions. Regions organize transform blocks and can be queried independently in JSON responses. Includes settings for default region and whether to collapse single-block regions.
/admin/structure/block/transform/region/add
Create a new transform block region for organizing transform blocks in JSON output.
/admin/structure/block/transform/add/{plugin_id}
Configure a transform block instance including its settings, region placement, and visibility conditions.
/admin/structure/types/manage/{bundle}/transform
Configure how fields of a content type are transformed to JSON for each transform mode. Select which field transform plugin to use for each field or hide fields from JSON output.
Permissions 4
Hooks 5
hook_transform_alter
Alter all transformation arrays as they are transformed. Called for every transform processed by the transformer.
hook_HOOK_transform_alter
Alter transformation arrays with a specific HOOK identifier. The HOOK is provided by the transform's getAlterIdentifiers() method, typically the transform type and entity type.
hook_blocks_transform_config_alter
Alter the configuration of transform blocks. Allows adding or modifying transform blocks programmatically.
hook_field_transform_third_party_settings_form
Add third-party settings to field transform configuration forms.
hook_field_transform_settings_summary_alter
Alter the settings summary displayed for field transforms in the UI.