Настройка Wagtail API для Headless-режима с GraphQL и webhooks

Headless CMS на Wagtail — отличная идея, пока не упираешься в ограничения встроенного REST API v2. Мы часто сталкиваемся с этим в проектах: он только read-only, нет мутаций, нет preview без костылей, а с изображениями приходится танцевать с бубном. Например, для интернет-магазина с каталогом 50 000 товаров нужно было организовать превью новых страниц до публикации. Стандартный API не отдает черновики — пришлось писать отдельный эндпоинт с токеном. Или для блога с регулярной публикацией постов требовалась мгновенная ревалидация страниц на 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 сегодня.