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