Интеграция 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 час онлайн)
• Поддержка в течение месяца после интеграции