Настройка Contentful Delivery API / Management API / Preview API

Настройка Contentful Delivery API / Management API / Preview API

Contentful предоставляет три отдельных HTTP API с разными токенами доступа и базовыми URL. Путаница между ними — типичная причина того, что в продакшене показывается черновой контент или изменения не сохраняются.

Три API и их назначение

Content Delivery API (CDA) — только чтение опубликованного контента. Базовый URL: https://cdn.contentful.com. Токен: delivery access token (read-only, можно коммитить в переменные окружения).

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. Никогда не используется на фронтенде.

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

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();

Переменные окружения для всех трёх API настраиваются в .env.local и в CI/CD pipeline отдельно для preview и production окружений.