Плутанина між трьома 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.
| API | URL | Токен | Призначення | Кешування |
|---|---|---|---|---|
| CDA | cdn.contentful.com | Delivery Token | Публічний контент | CDN (контролюється) |
| CPA | preview.contentful.com | Preview Token | Чернетки для редакторів | Немає |
| CMA | api.contentful.com | Management Token | CRUD контенту | Немає |
Як вибрати токен для середовища?
У .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: рішення — синхронізувати токен і простір на сервері та клієнті.
Таблиця налаштувань для середовищ
| Середовище | API | Токен | Кешування |
|---|---|---|---|
| production | CDA | Delivery | CDN (TTL 1 год) |
| staging | CPA | Preview | Немає |
| local | CMA | Management | Немає |
При помилці 401 перевірте, чи токен відповідає середовищу та чи не закінчився термін дії. Для CMA переконайтеся, що Personal Access Token має права на потрібний простір.
Процес налаштування під ключ
- Аналітика: збираємо вимоги до локалей, середовищ, типів контенту.
- Проєктування: визначаємо схему токенів, middleware для вибору API.
- Реалізація: пишемо ізольовані клієнти для CDA, CPA, CMA.
- Тестування: перевіряємо, що кожен токен працює у своєму середовищі, немає витоку чернеток у продакшен.
- Деплой: налаштовуємо CI/CD для автоматичної зміни токенів під час просування.
Офіційна документація Contentful Delivery API.
Терміни: від 3 до 7 днів залежно від складності проєкту. Вартість розраховується індивідуально після аудиту поточної інтеграції. Економія часу на вичитку контенту — до 40%.
Що входить у роботу
- Вихідний код модуля клієнта для CDA, CPA, CMA (TypeScript)
- Документація щодо змінних оточення та токенів
- Налаштування Draft Mode для редакторів
- Міграція існуючих запитів на новий клієнт
- Навчання команди (1 година онлайн)
- Підтримка протягом місяця після інтеграції
Типові помилки та чек-лист
- Використання Preview Token у продакшені → публіка не бачить новий контент.
- Відсутність обробки помилок (401/403) при ротації токенів.
- Зберігання Management Token у репозиторії.
- Завжди розділяйте середовища: production, staging, local.
- Використовуйте
.env.exampleіз коментарями.
Замовте аудит інтеграції у наших інженерів. Отримайте консультацію з налаштування Contentful: ми перевіримо вашу поточну схему та запропонуємо оптимізацію. Понад 5 років на ринку, 50+ проєктів з Contentful — ми гарантуємо, що інтеграція пройде без сюрпризів.