Разработка REST/JSON:API интеграции Drupal

Разработка REST/JSON:API интеграции Drupal

Drupal поставляется с двумя API-системами из коробки: REST (гибкий, требует настройки) и JSON:API (стандартизированный, работает сразу). JSON:API предпочтителен для headless-архитектур и мобильных приложений.

JSON:API — включение и первые запросы

drush en jsonapi -y

После включения все типы контента доступны автоматически. Формат URL: /jsonapi/{entity_type}/{bundle}.

# Список статей
curl https://site.com/jsonapi/node/article

# Конкретная нода по UUID
curl https://site.com/jsonapi/node/article/{uuid}

# Фильтрация
curl "https://site.com/jsonapi/node/article?filter[status]=1&filter[field_category.name]=News"

# Включение связанных ресурсов
curl "https://site.com/jsonapi/node/article?include=field_tags,uid"

# Сортировка и пагинация
curl "https://site.com/jsonapi/node/article?sort=-created&page[limit]=10&page[offset]=20"

# Выбор конкретных полей (sparse fieldsets)
curl "https://site.com/jsonapi/node/article?fields[node--article]=title,body,created"

Аутентификация для записи

JSON:API поддерживает GET без аутентификации (для публичного контента). POST/PATCH/DELETE требуют аутентификации.

# Базовая аутентификация (только для разработки)
curl -X POST https://site.com/jsonapi/node/article \
    -u admin:password \
    -H "Content-Type: application/vnd.api+json" \
    -d '{
        "data": {
            "type": "node--article",
            "attributes": {
                "title": "Новая статья",
                "body": { "value": "<p>Текст</p>", "format": "full_html" }
            }
        }
    }'

Для production — OAuth 2.0 через модуль simple_oauth:

composer require drupal/simple_oauth
drush en simple_oauth -y

Simple OAuth: настройка

1. Конфигурация → Simple OAuth → Generate keys
2. Создать OAuth Client: Конфигурация → Simple OAuth → Clients → Add Client
3. Назначить скоупы ролям

# Получение токена (Client Credentials)
curl -X POST https://site.com/oauth/token \
    -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=editor"

# Запрос с Bearer токеном
curl https://site.com/jsonapi/node/article \
    -H "Authorization: Bearer ACCESS_TOKEN"

REST API: кастомные ресурсы

// src/Plugin/rest/resource/ProductStockResource.php
namespace Drupal\mymodule\Plugin\rest\resource;

use Drupal\rest\Plugin\ResourceBase;
use Drupal\rest\ResourceResponse;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;

/**
 * @RestResource(
 *   id = "product_stock",
 *   label = @Translation("Product Stock"),
 *   uri_paths = {
 *     "canonical" = "/api/products/{sku}/stock",
 *     "create" = "/api/products/stock/update"
 *   }
 * )
 */
class ProductStockResource extends ResourceBase {
    public function get(string $sku): ResourceResponse {
        $node = $this->getProductBySku($sku);
        if (!$node) {
            throw new NotFoundHttpException("Product $sku not found");
        }

        $response = new ResourceResponse([
            'sku' => $sku,
            'stock' => (int) $node->get('field_stock_quantity')->value,
            'available' => (bool) $node->get('field_in_stock')->value,
        ]);
        $response->addCacheableDependency($node);
        return $response;
    }

    public function patch(array $data): ResourceResponse {
        $sku = $data['sku'] ?? throw new BadRequestHttpException('SKU required');
        $node = $this->getProductBySku($sku);
        $node->set('field_stock_quantity', $data['quantity']);
        $node->save();
        return new ResourceResponse(['updated' => true], 200);
    }
}

Включение ресурса: Конфигурация → Web Services → REST → включить product_stock.

Кастомный JSON:API фильтр

// Добавить вычисляемое поле к JSON:API ответу
use Drupal\jsonapi\ResourceType\ResourceTypeRepositoryInterface;

// Через hook_jsonapi_resource_type_field_alter
function mymodule_jsonapi_resource_type_field_alter(array &$fields, EntityTypeInterface $entity_type, string $bundle): void {
    if ($entity_type->id() === 'node' && $bundle === 'product') {
        $fields['price_with_discount'] = ResourceTypeField::toPublicName('price_with_discount');
    }
}

JSON:API Extras: дополнительная конфигурация

composer require drupal/jsonapi_extras
drush en jsonapi_extras -y

JSON:API Extras позволяет:

• Отключить эндпоинты для отдельных типов контента
• Изменить имена полей в ответе
• Добавить вычисляемые поля
• Настроить версионирование API

Кэширование ответов

Drupal автоматически кэширует JSON:API ответы через Cache API с учётом cache tags. При обновлении ноды — кэш для связанных запросов инвалидируется.

Добавить Varnish или Nginx FastCGI Cache перед Drupal для максимальной производительности публичных API-эндпоинтов.

Сроки

Базовая настройка JSON:API с OAuth аутентификацией — 2–3 дня. Кастомные REST-ресурсы и JSON:API Extras — плюс 2–3 дня.