Настройка Statamic как Headless CMS через REST/GraphQL API

Настройка Statamic как Headless CMS через REST/GraphQL API

Statamic поддерживает headless-режим через встроенный Content API (REST) и официальный GraphQL аддон. REST API доступен в бесплатной версии, GraphQL — в Pro.

REST API

Включение в config/statamic/api.php:

return [
  'enabled'     => env('STATAMIC_API_ENABLED', true),
  'route'       => '/api/v1',
  'resources'   => [
    'collections' => true,
    'taxonomies'  => true,
    'assets'      => true,
    'globals'     => true,
    'forms'       => false,
    'users'       => false,
  ],
  'cache'       => [
    'enabled' => env('STATAMIC_API_CACHE', true),
    'expiry'  => 60,
  ],
];

Доступные endpoints:

GET /api/v1/collections
GET /api/v1/collections/{collection}/entries
GET /api/v1/collections/{collection}/entries/{id}
GET /api/v1/taxonomies/{taxonomy}/terms
GET /api/v1/globals
GET /api/v1/globals/{handle}
GET /api/v1/assets/{container}

Фильтрация и выборка через REST

// Список постов с фильтрацией
const res = await fetch(
  `${STATAMIC_URL}/api/v1/collections/blog/entries?` +
  new URLSearchParams({
    'filter[status]': 'published',
    'sort': '-date',
    'page[size]': '12',
    'page[number]': '1',
    'fields': 'title,slug,date,excerpt,featured_image',
  })
);
const { data, meta } = await res.json();

GraphQL API (Pro)

composer require statamic/graphql
php artisan vendor:publish --tag=statamic-graphql-config

Настройка схемы:

// config/statamic/graphql.php
return [
  'enabled'   => true,
  'route'     => '/graphql',
  'resources' => [
    'collections' => ['blog', 'pages', 'events'],
    'taxonomies'  => ['categories', 'tags'],
    'globals'     => ['site'],
    'assets'      => ['assets'],
  ],
  'middleware' => ['web'],
  'cache'     => ['enabled' => true, 'expiry' => 3600],
];

Запросы:

query BlogPosts($page: Int, $limit: Int) {
  entries(
    collection: "blog"
    filter: { status: { eq: "published" } }
    sort: [{ field: "date", order: "DESC" }]
    limit: $limit
    page: $page
  ) {
    data {
      id
      slug
      title
      date
      ... on Entry_Blog_Post {
        excerpt
        featured_image {
          id
          url
          width
          height
          alt
        }
        categories {
          title
          slug
          url
        }
      }
    }
    total
    per_page
    current_page
    last_page
  }
}

Кастомный GraphQL-тип

// Расширение схемы через аддон
use Statamic\Facades\GraphQL;
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

GraphQL::addType(new ObjectType([
  'name'   => 'PostStats',
  'fields' => [
    'views' => ['type' => Type::int()],
    'likes' => ['type' => Type::int()],
  ],
]));

// Добавление поля к существующему типу Entry
GraphQL::addField('Entry_Blog_Post', 'stats', function () {
  return [
    'type'    => GraphQL::type('PostStats'),
    'resolve' => function ($entry) {
      return [
        'views' => PostStats::getViews($entry->id()),
        'likes' => PostStats::getLikes($entry->id()),
      ];
    },
  ];
});

Next.js + Statamic REST

// lib/statamic.ts
const BASE = process.env.STATAMIC_URL!;

export async function getBlogPosts(page = 1) {
  const url = new URL(`${BASE}/api/v1/collections/blog/entries`);
  url.searchParams.set('filter[status]', 'published');
  url.searchParams.set('sort', '-date');
  url.searchParams.set('page[size]', '12');
  url.searchParams.set('page[number]', String(page));

  const res = await fetch(url.toString(), {
    next: { revalidate: 3600, tags: ['blog'] },
  });
  return res.json();
}

// Webhook для revalidation при публикации
// Statamic → CP → Utilities → API → Webhooks
// Event: entry:saved → POST https://nextjs.app/api/revalidate

Настройка REST API с базовыми endpoint-ами — 4–8 часов. GraphQL с кастомными типами — 1–2 дня.