Розробка 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. Призначити scopes ролям

# Отримання токена (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 дні.