Drupal как headless CMS: какой API выбрать

Headless-режим Drupal часто начинают с идеи «подключим фронтенд к базе контента через API». На практике выбор интерфейса определяет почти всё: сколько запросов понадобится странице, как настроить права редакторов, можно ли кешировать ответы и насколько дорого менять модель данных. Для Drupal 10.x и 11.x базовой точкой обычно служит JSON:API из ядра, но для сложных выборок иногда оправданы REST или GraphQL.

Что сравниваем перед выбором API

В headless-схеме Drupal отвечает за контент, пользователей, медиа и редакторские процессы, а отдельное приложение — за HTML, маршрутизацию и пользовательский интерфейс. Между ними появляется API-контракт. Если выбрать его только по удобству первого запроса, проблемы проявятся позже: фронтенд начнёт делать десятки обращений, права доступа окажутся неочевидными, а изменение типа материала потребует переделки нескольких клиентов.

Сравнивать варианты стоит по четырём критериям:

• насколько быстро можно получить типы материалов и поля;
• как клиент запрашивает связи, изображения и вложенные сущности;
• что происходит с правами доступа, кешем и инвалидированием;
• сколько серверной и клиентской логики потребуется поддерживать.

Главный выбор — не между форматами JSON. Вы выбираете границу ответственности: отдаёт ли Drupal свои сущности почти напрямую или команда создаёт отдельный контракт для каждого клиента.

Сноска. Headless CMS — система управления контентом без обязательного встроенного пользовательского интерфейса сайта. Drupal остаётся редакторской и контентной платформой, а витрина получает данные по API.

Три рабочих подхода в Drupal

JSON:API из ядра: стартовый вариант для сущностей Drupal

JSON:API в Drupal 10 и 11 предназначен для работы с сущностями: материалами, пользователями, терминами таксономии, медиа и другими типами, доступными через конфигурацию сайта. Он использует стандартную структуру JSON:API, поэтому клиент получает предсказуемые ссылки, идентификаторы, атрибуты и отношения.

Его сильная сторона — короткий путь от созданного типа материала до первого ответа. Если у вас есть тип «Статья», ресурс обычно доступен через маршрут вида /jsonapi/node/article, где article — машинное имя типа материала. Точный URL зависит от машинынного имени и включённых ресурсов, а не от заголовка, который видит редактор.

curl -H "Accept: application/vnd.api+json" \
  "https://example.com/jsonapi/node/article?filter[status]=1&page[limit]=10&sort=-created"

Такой запрос получает опубликованные материалы и ограничивает страницу десятью записями. Для продакшена нужно отдельно определить поля через параметры fields, связи через include, фильтры и сортировки. Не стоит отдавать фронтенду весь объект «на всякий случай»: схема ответа станет тяжелее, а изменение поля может неожиданно повлиять на клиентов.

Цена простоты — модель запроса диктуется сущностями Drupal. Если странице нужна специально собранная выдача из материалов, товаров, профилей и вычисляемых значений, клиенту может понадобиться несколько запросов. Вопросы агрегации, сложных условий и единого DTO* придётся решать отдельно.

REST: когда нужен управляемый ресурс

REST-модули Drupal позволяют описывать ресурсы и методы более явно: какие операции доступны, какой формат ответа использовать, какие способы аутентификации разрешить. Это полезно, когда API должен быть не зеркалом сущностей, а договором с конкретным приложением или внешней системой.

Практическая цена — конфигурация. Для каждого ресурса нужно продумать маршруты, методы, сериализацию, доступ и обработку ошибок. REST не превращает сложную бизнес-операцию в готовый endpoint автоматически. Если вы публикуете заказ, запускаете импорт или меняете несколько сущностей одной командой, потребуется собственный код и тесты.

REST выбирают, когда команда хочет контролировать URL и формат ответа, а также когда интеграция уже построена вокруг отдельных ресурсов. Для обычного каталога или блога он часто даёт больше ручной работы, чем JSON:API.

GraphQL: один контракт для выборок клиента

GraphQL в Drupal обычно добавляют сторонним модулем. Он позволяет клиенту описать нужные поля в запросе и получить ответ с такой же структурой. Это удобно для страниц, где мобильному приложению, веб-витрине и поисковому интерфейсу нужны разные срезы одних и тех же данных.

Плюс GraphQL — меньше лишних полей и возможность собрать связанные данные одним запросом. Минусы появляются на эксплуатации: нужно следить за сложностью запросов, глубиной вложенности, кешированием и доступом к каждому полю. Кроме того, модуль и его совместимость с конкретной версией Drupal нужно проверять отдельно на странице проекта. Не переносите GraphQL-конфигурацию с Drupal 10 на 11 без проверки зависимостей.

GraphQL не отменяет проектирование схемы. Если дать клиенту слишком широкий доступ к связям, запрос может стать дорогим для базы данных. Ограничения глубины и стоимости запросов должны появиться до публикации API, а не после первого инцидента.

Сравнение вариантов

Как выбрать без переделки через месяц

Берите JSON:API, если структура страницы следует модели контента

Это разумный выбор для новостей, справочников, корпоративных сайтов и каталогов, где фронтенд показывает сущности Drupal и их связи. Начните с одного типа материала, одной медиа-сущности и реального экрана. Проверьте не только успешный ответ, но и ситуацию, когда редактор снял публикацию или у пользователя нет доступа.

Если JSON:API даёт слишком много запросов, сначала проверьте выбор полей, включение связей и стратегию кеша. Переход на GraphQL не должен быть способом скрыть неудачную модель данных.

Берите REST, если контракт важнее универсальности

REST оправдан для интеграции с конкретным приложением, платёжным контуром, внутренним кабинетом или внешней системой, которой нельзя отдавать всю модель Drupal. Зафиксируйте для каждого ресурса метод, входные данные, ответ, ошибки и правила доступа. Если этого не сделать, REST быстро превратится в набор несогласованных маршрутов.

Берите GraphQL, если выборки действительно различаются

GraphQL имеет смысл, когда один и тот же контент собирают разные приложения, а фиксированный набор REST-ответов разрастается. До внедрения составьте несколько настоящих запросов: главная страница, карточка материала, поиск и экран редактора. Измерьте число обращений к базе и время ответа, затем задайте ограничения на глубину и объём выборки.

Что ломается на практике

• API отдаёт черновики. Проверяйте публикационный статус, права пользователя и поведение анонимного запроса. Фильтр в клиенте не заменяет серверный контроль доступа.
• Изображения работают на тесте, но не в проде. Уточните публичность файлов, схемы URL, домен CDN и размеры производных изображений. Ссылка на файл — часть контракта, а не случайная строка в ответе.
• Страница делает много запросов. Посчитайте обращения в браузере и проверьте, можно ли запросить связанные сущности через include в JSON:API или одним GraphQL-запросом. Если данные живут в разных источниках, один запрос не всегда будет быстрее.
• Кеш отдаёт старую публикацию. Определите, кто инвалидирует кеш после сохранения материала, сколько живёт ответ и как CDN различает анонимных и авторизованных пользователей.
• Клиент зависит от внутреннего имени поля. Не переименовывайте машинные имена без миграции и не используйте отображаемые заголовки как идентификаторы. Машинное имя — стабильная часть API-контракта, если команда его таковым объявила.

Что измерить до выбора

Соберите четыре сценария на тестовой копии Drupal: список материалов, карточка со связанной медиа, поиск и запрос пользователя с ограниченными правами. Для каждого зафиксируйте число HTTP-запросов, размер ответа, время до первого байта, время ответа базы и долю ответов из кеша. Точных универсальных цифр здесь нет: результат зависит от числа полей, индексов, подключённых модулей, PHP, базы данных и CDN.

Сравнивайте варианты на одинаковом наборе данных и с одинаковым прогревом кеша. Отдельно прогоните сценарий после публикации материала: именно здесь обнаруживаются проблемы с инвалидированием, а не в красивом тесте на пустом сайте.

Что делать дальше

Для нового проекта начните с JSON:API и опишите контракт одного экрана: ресурсы, поля, связи, фильтры, права и кеш. Если не хватает контроля над форматом или операциями, вынесите только проблемный участок в REST. GraphQL подключайте после замеров, когда различия клиентских выборок подтверждены, а не потому, что один запрос выглядит аккуратнее.

Следующий практический шаг — добавить контрактные тесты на опубликованный материал, черновик, удалённую медиа-сущность и пользователя без права просмотра. Это дешевле, чем обнаружить несовместимость API после релиза фронтенда.