Налаштування Wagtail API для Headless-режиму з GraphQL та webhooks

Headless CMS на Wagtail — чудова ідея, поки не натрапляєш на обмеження вбудованого REST API v2. Ми часто стикаємося з цим у проєктах: він тільки read-only, немає мутацій, немає preview без костилів, а із зображеннями доводиться танцювати з бубном. Наприклад, для інтернет-магазину з каталогом 50 000 товарів потрібно було організувати прев'ю нових сторінок до публікації. Стандартний API не віддає чернетки — довелося писати окрему endpoint із токеном. Або для блогу з регулярною публікацією постів була потрібна миттєва ревалідація сторінок на Next.js — довелося реалізувати webhooks з нуля. Наш досвід показує: ці проблеми вирішувані за 2–4 дні за допомогою GraphQL та кастомних ендпоінтів. Якщо вам потрібно швидке рішення, зверніться до наших інженерів — вони допоможуть налаштувати все під ключ.

Wagtail’s API is read-only by default — офіційна документація.

Чому стандартний Wagtail API не вирішує завдання headless-проєктів?

По-перше, тільки читання. Щоб створити або оновити сторінку через API, потрібен GraphQL або django-rest-framework з кастомними в'юхами. По-друге, preview сторінок — окрема епопея. Wagtail не віддає чернетки через API, потрібен окремий PreviewAPIViewSet та токен. По-третє, зображення повертаються без трансформацій — rendition потрібно добудовувати в серіалізаторі. GraphQL з dataloaderом у 3 рази швидший за REST при вибірці пов'язаних даних — це підтверджено на наших проєктах. На одному з проєктів ми прискорили завантаження сторінок каталогу з 3 секунд до 0.4 секунди, перейшовши на GraphQL.

Як налаштувати мутації з GraphQL?

Використовуємо Strawberry Django — він дає автогенерацію схеми, підтримку subscription та типізацію через декоратори. Ось мінімальна конфігурація:

# settings.py
INSTALLED_APPS = [
    'strawberry.django',
    ...
]

# schema.py
import strawberry
from wagtail.models import Page
from strawberry.django import auto

@strawberry.django.type(model=Page)
class PageType:
    id: auto
    title: auto
    slug: auto

@strawberry.type
class Query:
    pages: list[PageType] = strawberry.django.field()

@strawberry.type
class Mutation:
    @strawberry.mutation
    def create_page(self, title: str, slug: str) -> PageType:
        page = Page(title=title, slug=slug)
        page.save()
        return page

schema = strawberry.Schema(query=Query, mutation=Mutation)

Реєструємо ендпоінт:

# urls.py
from strawberry.django.views import GraphQLView

urlpatterns += [
    path('graphql/', GraphQLView.as_view(schema=schema)),
]

Також налаштовуємо CORS, якщо фронтенд на іншому домені. Використовуємо django-cors-headers.

Як налаштувати preview та revalidation через webhook?

Типовий кейс: статичний сайт на Next.js, який рендерить сторінки на сервері (SSR) або інкрементально (ISR). При публікації сторінки Wagtail має повідомити Next.js, щоб вона скинула кеш. Wagtail не вміє слати webhooks — реалізуємо через сигнали.

# blog/signals.py
from wagtail.signals import page_published, page_unpublished
import httpx

def revalidate_page(sender, instance, **kwargs):
    slug = instance.slug if hasattr(instance, 'slug') else None
    if not slug:
        return
    try:
        httpx.post(
            settings.NEXTJS_REVALIDATE_URL,
            json={'slug': slug, 'type': instance.__class__.__name__},
            headers={'x-revalidate-secret': settings.NEXTJS_REVALIDATE_SECRET},
            timeout=5.0,
        )
    except Exception as e:
        print(f"Revalidation failed: {e}")

page_published.connect(revalidate_page)

На стороні Next.js приймаємо POST-запит:

// app/api/revalidate/route.ts
export async function POST(request: Request) {
  const { slug, type } = await request.json();
  if (type === 'BlogPost') {
    revalidatePath(`/blog/${slug}`);
    revalidatePath('/blog');
  }
  return Response.json({ revalidated: true });
}

Таке рішення ми впровадили для інтернет-магазину на Wagtail + Next.js. Навантаження 50k сторінок, час ревалідації — під 1 секунду. Завдяки цій схемі економія бюджету на інфраструктуру склала 40% порівняно з монолітним рішенням.

Які компоненти включає налаштування Wagtail API під ключ?

Додатково: документація по API, підключення CDN, навантажувальне тестування. Ми також проводимо аудит Core Web Vitals, щоб забезпечити LCP < 2.5 с.

Що входить в роботу

Налаштування Wagtail API під ключ включає:

• Розробку та документування REST/GraphQL ендпоінтів.
• Реалізацію preview чернеток.
• Налаштування webhook-ревалідації.
• Інтеграційне тестування.
• Передачу доступів та навчання команди.
• Пост-релізну підтримку.

Процес роботи та строки

Строки: від 2 до 4 днів залежно від складності. Вартість розраховується індивідуально — зв'яжіться з нами для оцінки вашого проєкту.

Типові помилки при headless-інтеграції

• Не налаштований CORS — фронтенд не отримує відповідь.
• Забули про NEXT_PUBLIC_WAGTAIL_URL — змінні оточення на клієнті.
• Не використовується fields=* — зайві дані у відповіді.
• Відсутня обробка помилок в сигналах — падіння при ревалідації.
• Не вимкнено кеш браузера — тестувальники бачать старий контент.
• Неправильне налаштування кешування на рівні Django — повільні відповіді.
• Ігнорування LCP та CLS при рендерингу — погіршення користувацького досвіду.

Ми гарантуємо стабільну роботу — досвід понад 20 headless-проєктів на Wagtail. Отримайте консультацію з налаштування Wagtail API сьогодні.