min read
December 4, 2023
December 4, 2023

Introduction to Transform API

Introduction to Transform API
Table of contents

The Transform API is a recently contributed Drupal module, designed to simplify the creation of JSON content from various Drupal elements such as entities and menus. It provides a smooth way for developers familiar with Drupal's entity system, view modes, and templates to effortlessly convert them into JSON, using either configuration or code.

While Drupal traditionally served HTML content, there's a shift towards headless or decoupled architectures, where content is delivered as JSON. This is precisely where the Transform API excels. Leveraging Drupal’s responsive image module, Transform API ensures images are provided in multiple formats, contributing to improved image quality and enhanced performance for decoupled sites.

The Transform API brings together familiar elements like blocks (transform blocks), view modes (transform modes), and formatters (transformers). It also includes techniques, such as lazy_builders (lazy_transformers) and preprocess (transform_alter).

Let’s consider some key terminologies related to the Transform API.

Terminologies related to Transform API

Transform blocks

In Drupal, the Block Layout refers to the system and user interface that helps arrange and display blocks on your website. Similarly, Transform blocks allow you to manage the placement, visibility, and layout of the blocks in the JSON version of the website.

The Transform API includes a new Transform blocks tab (/admin/structure/block/transform ) within Drupal's main block layout settings page. Here, regions and blocks can be configured for the JSON output. These Transform blocks work similarly to regular blocks, except they use preconfigured regions rather than theme regions.

Transform blocks
Manage Transform Tab (similar to Block Layout Tab).

Manage Transform Tab
JSON response of the homepage. The response structure follows the Transform blocks layout.

Transform modes

Drupal core has default display modes: view modes and form modes. The Transform API introduces "transform mode" - this works like the view mode but for JSON output instead of HTML.

Developers can add new transform modes in the Drupal backend under Structure → Display modes → Transform modes or use the path /admin/structure/display-modes/transform. These new transform modes can then be used for entities, similarly to view and form modes configured in the field UI.

Transform field formatter (Transformers)

The field formatter in Drupal lets you customize how field data is displayed on web pages. The Transform API has "Transform field formatter" that does the same for JSON output. These formatters control what field content gets included in headless APIs and structures.

Display Modes
Transform Modes

Regular field formatters display data as HTML for web pages. Transform field formatters present data as JSON for APIs instead. Transform modes can provide different modes for representing the same entity.

Manage Transform
Manage transform option available on the article content type to handle the JSON format of the field data.

Difference between JSON API and Transform API

The Transform API module takes advantage of Drupal's existing functionality. It prepares images and content so they are ready for decoupled sites. The JSON:API module mainly returns raw entity data. It requires the frontend to process images and content after receiving them.

For example, the Transform API provides images in multiple sizes for responsive sites. Its workflow matches typical Drupal development.

Check out the difference between the JSON API response and the Transform API response for article content.

Transform API response

Transform API response

JSON API response

1. Article entity response.

Article entity response

2. Image entity response.

Image entity response

Benefits of Transform API

  • Easy to use without special coding skills.
  • Converts any Drupal entities like nodes, users, or taxonomy terms into JSON.
  • Generates JSON for different view modes and templates.
  • Creates headless backend content for decoupled Drupal sites.


Summing up

The Transform API module simplifies creating JSON data from Drupal. It reuses existing skills for Drupal developers while meeting the needs for headless systems. If you are looking for a way to create JSON content from Drupal entities, then the Transform API Drupal module is a good option to consider.

Written by
No art workers.
We'd love to talk about your business objectives