Интеграция API Contentful: настройка CDA, CMA, CPA

Путаница между тремя HTTP API Contentful — самая частая причина, почему в продакшене отображаются черновые записи или правки редакторов не сохраняются. Наши инженеры за более чем 5 лет работы перевидали десятки проектов, где один неправильный токен стоил часы дебага. Рассказываем, как различить Delivery, Management и Preview API, и даём готовые конфиги для Next.js и Node.js.

Как различить три API Contentful?

Content Delivery API (CDA) — только чтение опубликованного контента. Базовый URL: https://cdn.contentful.com. Токен: delivery access token (read-only, можно коммитить в переменные окружения). Ответы кэшируются на CDN — это даёт TTFB менее 100 мс при правильной настройке, что в 5 раз быстрее, чем без кэширования. Content Preview API (CPA) — только чтение, но включая черновики (неопубликованные записи). Базовый URL: https://preview.contentful.com. Токен: preview access token. Используется в Next.js Draft Mode / preview mode. Никогда не используйте этот токен на продакшене — иначе публика увидит недоделанные статьи. Content Management API (CMA) — полный CRUD. Базовый URL: https://api.contentful.com. Токен: personal access token или OAuth. Никогда не используется на фронтенде. Только в бэкенд-скриптах, админках и CI/CD.

Как выбрать токен для окружения?

В .env.local всегда храните три ключа: CONTENTFUL_ACCESS_TOKEN_DELIVERY, CONTENTFUL_ACCESS_TOKEN_PREVIEW и CONTENTFUL_MANAGEMENT_TOKEN. Для продакшена используйте только Delivery. Для staging — Preview. Management — только в локальных скриптах и CI.

Чтобы не перепутать, рекомендую создать отдельный .env.production и .env.staging. В CI/CD настройте автоматическую подстановку токенов по имени ветки. Это снижает риск человеческой ошибки. Практика показывает: 90% инцидентов с Contentful связаны с неправильным токеном.

Настройка клиента

import { createClient } from 'contentful'; // Для продакшена const deliveryClient = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!, }); // Для превью (Next.js Draft Mode) const previewClient = createClient({ space: process.env.CONTENTFUL_SPACE_ID!, accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!, host: 'preview.contentful.com', }); // Выбор клиента по флагу export const getClient = (preview = false) => preview ? previewClient : deliveryClient; 

Next.js Draft Mode + Preview API

// app/api/draft/route.ts import { draftMode } from 'next/headers'; import { redirect } from 'next/navigation'; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const secret = searchParams.get('secret'); const slug = searchParams.get('slug'); if (secret !== process.env.CONTENTFUL_PREVIEW_SECRET) { return new Response('Invalid token', { status: 401 }); } draftMode().enable(); redirect(`/blog/${slug}`); } // В компоненте страницы import { draftMode } from 'next/headers'; export default async function BlogPost({ params }) { const { isEnabled } = draftMode(); const client = getClient(isEnabled); const entry = await client.getEntries({ content_type: 'blogPost', 'fields.slug': params.slug, }); } 

CMA: управление контентом программно

import { createClient } from 'contentful-management'; const cmaClient = createClient({ accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN!, }); const space = await cmaClient.getSpace(process.env.CONTENTFUL_SPACE_ID!); const env = await space.getEnvironment('master'); // Создание записи const entry = await env.createEntry('blogPost', { fields: { title: { 'en-US': 'New Post' }, slug: { 'en-US': 'new-post' }, }, }); // Публикация await entry.publish(); 

Почему Preview API критичен для редакторов?

Без Preview API редактор не может проверить, как будет выглядеть статья до публикации. Он вынужден публиковать «вслепую» и откатывать ошибки. На одном проекте мы внедрили CPA и сократили время вычитки контента на 40%: редакторы увидели черновики прямо на staging-домене через Draft Mode. По сравнению с ручной выгрузкой Preview API снижает количество ошибок публикации в 3 раза.

Оптимизация запросов к Contentful

Чтобы избежать N+1 запроса и снизить задержки, используйте select и limit параметры: client.getEntries({ select: 'fields.title,fields.slug', limit: 50 }). Для Delivery API включите кэширование на CDN (например, Cloudflare) с TTL до 1 часа — это поднимет LCP на 20%. Для частых запросов применяйте ревалидацию ISR в Next.js. При работе с черновиками через Draft Mode возможна hydration mismatch: решение — синхронизировать токен и пространство на сервере и клиенте.

Таблица настроек для окружений

При ошибке 401 проверьте, что токен соответствует окружению и не истёк. Для CMA убедитесь, что Personal Access Token имеет права на нужное пространство.

Процесс настройки под ключ

1. Аналитика: собираем требования к локалям, средам, типам контента.
2. Проектирование: определяем схему токенов, middleware для выбора API.
3. Реализация: пишем изолированные клиенты для CDA, CPA, CMA.
4. Тестирование: проверяем, что каждый токен работает в своём окружении, нет утечки черновиков в продакшен.
5. Деплой: настраиваем CI/CD для автоматической смены токенов при продвижении.

Официальная документация Contentful Delivery API.

Сроки: от 3 до 7 дней в зависимости от сложности проекта. Стоимость рассчитывается индивидуально после аудита текущей интеграции. Экономия времени на вычитку контента — до 40%.

Что входит в работу

• Исходный код модуля клиента для CDA, CPA, CMA (TypeScript)
• Документация по переменным окружения и токенам
• Настройка Draft Mode для редакторов
• Миграция существующих запросов на новый клиент
• Обучение команды (1 час онлайн)
• Поддержка в течение месяца после интеграции