Свързване на уебсайт към CMS API

API-то на CMS позволява на вашия уебсайт да извлича и визуализира публикувано съдържание от Profound CMS. Можете да го използвате, за да захранвате страници с документация, маркетингови страници, блогове, центрове за помощ или всяко друго преживяване, водено от съдържание.

Типичната интеграция има три части:

1. Конфигурирайте връзката си с CMS
2. Извлечете публикуваното съдържание
3. Рендерирайте съдържанието във вашето приложение

Конфигурация

За да свържете приложението си към CMS, предоставете URL адреса на CMS API, идентификатора на уебсайта и 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('Failed to fetch CMS post', error);
    return null;
  }
}

Сигурност

Пазете API ключовете поверителни и ги използвайте само на сървъра. Не включвайте частни идентификационни данни в браузърни пакети или публичен JavaScript.

Използвайте публични променливи на средата само за нечувствителни стойности като:

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

Използвайте частни променливи на средата за:

• API ключове
• токени за визуализация
• административни идентификационни данни
• секрети за внедряване

Обобщение

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

Стандартната интеграция трябва да:

• Конфигурира URL на CMS, идентификатор на уебсайт и API ключ.
• Извлича документи по схема.
• Извлича страници по път на маршрута.
• Визуализира CMS блокове с вашите собствени компоненти.
• Кешира публикуваното съдържание.
• Поддържа съдържанието за визуализация динамично.
• Пази частните идентификационни данни на сървъра.