Підключення вебсайту до API

API CMS дозволяє вашому вебсайту отримувати та відображати опублікований контент із Profound CMS. Ви можете використовувати її для створення сторінок документації, маркетингових сторінок, блогів, довідкових центрів або будь-якого іншого досвіду, керованого контентом.

Типова інтеграція складається з трьох частин:

1. Налаштуйте підключення до CMS
2. Отримайте опублікований контент
3. Відобразіть контент у своєму застосунку

Налаштування

Щоб підключити ваш застосунок до CMS, надайте URL API CMS, ідентифікатор вебсайту та ключ API.

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

Використовуйте змінні середовища для значень, які відрізняються між середовищами:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

Не розкривайте приватні ключі API в клієнтському коді. Ключі API слід використовувати на вашому сервері, у процесі збирання або у бекенд-маршрутах.

Отримання контенту

Контент у CMS організовано за схемами. Наприклад, ваш проєкт може мати схеми на кшталт post, category, page або section.

Використовуйте назву схеми, щоб отримати контент:

const posts = await cms.schema('post').fetchAll();

Щоб отримати окремий документ за ID:

const post = await cms.schema('post').fetchSingleById('document-id');

Щоб отримати локалізований контент, запросіть перекладену версію схеми:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

Відображення маршрутів

Для вебсайтів, які використовують сторінки під керуванням CMS, ви можете отримувати контент на основі поточного шляху URL.

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

Відповідь маршруту визначає сторінку та блоки для відображення. Потім ваш застосунок може отримати блоки та відрендерити їх за допомогою власних компонентів.

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

Приклад: відображення сторінки документації

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

Повернуті блоки можна використати, щоб відобразити сторінку за допомогою системи компонентів вашого застосунку.

Кешування

Опублікований контент CMS безпечно кешувати. Для більшості вебсайтів кешуйте відповіді API на короткий період і перевалідовуйте їх, коли контент змінюється.

Поширена конфігурація:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

Рекомендована поведінка кешу:

• Кешуйте запити до опублікованого контенту.
• Використовуйте коротші вікна кешу для часто оновлюваного контенту.
• Використовуйте теги кешу, якщо ваша платформа підтримує інвалідцію на вимогу.
• Уникайте кешування контенту попереднього перегляду або чернеток.

Режим попереднього перегляду

Режим попереднього перегляду дозволяє редакторам бачити неопубліковані зміни перед публікацією.

Поширений підхід — використовувати окремий маршрут попереднього перегляду, наприклад:

/docs/getting-started
/cms-preview/docs/getting-started

Продакшн-сторінки мають отримувати лише опублікований контент. Сторінки попереднього перегляду можуть приймати параметри попереднього перегляду, наприклад:

?edit_mode=true

Маршрути попереднього перегляду зазвичай мають бути динамічними і не повинні статично кешуватися.

Обробка помилок

Контент CMS може бути недоступний під час збирання або запиту. Ваш застосунок має обробляти це коректно.

Рекомендована поведінка:

• Поверніть 404, якщо маршрут не існує.
• Поверніть порожній список, коли необов’язковий навігаційний контент неможливо завантажити.
• Логуйте помилки отримання на стороні сервера.
• Уникайте розкриття внутрішніх помилок API відвідувачам.

Приклад:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Не вдалося отримати допис CMS', error);
    return null;
  }
}

Безпека

Зберігайте ключі API в таємниці та використовуйте їх лише на сервері. Не додавайте приватні облікові дані до браузерних бандлів або публічного JavaScript.

Публічні змінні середовища використовуйте лише для нечутливих значень, таких як:

• Публічний URL CMS
• Ідентифікатор вебсайту
• Конфігурація локалі

Приватні змінні середовища використовуйте для:

• Ключів API
• токенів попереднього перегляду
• облікових даних адміністратора
• секретів розгортання

Підсумок

Використовуйте API CMS, коли вашому вебсайту потрібно отримувати структурований контент, відображати маршрути під керуванням CMS або підтримувати робочі процеси попереднього перегляду для редакторів.

Стандартна інтеграція має:

• Налаштувати URL CMS, ідентифікатор вебсайту та ключ API.
• Отримувати документи за схемою.
• Отримувати сторінки за шляхом маршруту.
• Відображати блоки CMS за допомогою власних компонентів.
• Кешувати опублікований контент.
• Залишати контент попереднього перегляду динамічним.
• Зберігати приватні облікові дані на сервері.