Улучшение документации API Discourse для создания полностью кастомного фронтенда сообщества

Разработка
1

Всем привет :waving_hand:

Я разрабатываю кастомный фронтенд, используя Discourse в качестве headless-бэкенда (архитектура на базе Next.js), и хочу поделиться некоторыми практическими пробелами, с которыми я столкнулся в текущем дизайне API с точки зрения реальной интеграции.

Это не критика самого Discourse (он мощный и гибкий), а скорее обратная связь для улучшения разработческого опыта (DX) в современных архитектурах «фронтенд + API».

1. Пагинация и структура постов темы

Текущая проблема:

  • Пагинация не всегда согласована между конечными точками.

  • Посты темы (/t/{id}.json) смешивают:

    • оригинальный пост;

    • ответы;

    • внутренние метаданные.

Это усложняет создание чистого бесконечного скролла или нормализованного состояния (Redux/Zustand/React Query).

Предложение:

  • Обеспечить более четкое разделение или добавить опциональные флаги запроса, такие как:

    • ?include_first_post=true|false;

    • ?posts_only=replies;

    • Поддержка пагинации на основе курсоров (вместо только пагинации по страницам).

2. Ответы против структуры темы

На данный момент:

  • Ответы встроены в ответ темы.

  • Нет четкого разделения между:

    • «метаданными темы»;

    • «потоком постов».

Это вызывает:

  • лишнюю логику парсинга во фронтенде;

  • дублирование при нормализации состояния.

Предложение:

  • Предложить выделенные конечные точки, такие как:

    • /t/{id}/posts;

    • /t/{id}/replies;

    • или поддержку фильтрации внутри /t/{id}.json.

3. Отсутствие документации по уровням полей в ответе API

Например, в ответе темы:

  • created_at;

  • bumped_at;

  • last_posted_at;

  • updated_at.

Эти поля не всегда четко дифференцированы.

Проблема:

  • Разработчики часто неправильно интерпретируют:

    • bumped_at против updated_at;

    • что именно триггерит «активность темы».

Предложение:

  • Добавить встроенную документацию схемы или метаданные в стиле OpenAPI:

    • значение каждого поля;

    • объяснение жизненного цикла.

4. Несоответствия в статистике и кэшировании

Проблемы:

  • posts_count, reply_count, participants_count иногда отстают от данных в реальном времени.

  • Сильная зависимость от кэшированных счетчиков.

Влияние:

  • неточный интерфейс (особенно для дашбордов / страниц аналитики);

  • необходимость дополнительных вызовов API для проверки состояния.

Предложение:

  • Добавить индикатор «реальное время против кэш» или вариант конечной точки;

  • Или предоставить вебхуки/события для обновления счетчиков.

5. Пробелы в интеграции карты сайта, SEO и фреймворков

При интеграции с современными фреймворками (Next.js, Nuxt и др.):

Проблемы:

  • Нет единого API для:

    • обновленных тем для генерации карты сайта;

    • отслеживания последнего изменения на уровне категории;

    • полной поддержки индексации постов.

Разработчики вынуждены делать:

  • несколько вызовов API на категорию;

  • ручное сравнение для updated_at;

  • обход пагинации для обнаружения обновлений.

Предложение:

  • Добавить выделенные конечные точки:

    • /categories/updated;

    • /topics/changes?since=timestamp;

    • /sitemap.json (API-канал карты сайта).

6. Отсутствующие метрики пользователей и агрегации

Часто требуемые данные:

  • общее количество полученных лайков на пользователя;

  • общее количество отданных лайков;

  • детализация реакций на пост/пользователя;

  • статистика вовлеченности по категории.

Текущая проблема:

  • требует нескольких конечных точек + агрегации на фронтенде.

Предложение:

  • Добавить агрегированные конечные точки, такие как:

    • /users/{id}/stats;

    • /topics/{id}/stats.

7. Гибкость аватаров пользователей

Текущее ограничение:

  • Аватары тесно связаны с системой загрузки Discourse.

Запрос:

  • Разрешить внешние URL аватаров (S3 / CDN / внешние провайдеры аутентификации).

  • Поддержка:

    • external_avatar_url.

Это поможет в:

  • системах SSO;

  • headless-провайдерах идентификации.

8. Ключи API: администраторские против пользовательских

Требуется уточнение в документации:

Разница между:

  • администраторским ключом API;

  • пользовательским ключом API (создаваемым через /admin/api/keys или пользовательские конечные точки API).

Вопросы:

  • правила жизненного цикла и истечения срока действия;

  • правила отзыва для конкретного пользователя против глобальных;

  • ограничения области безопасности по типам.

Это критично при создании интеграций уровня продакшн.

Итоговые мысли

API Discourse уже мощный, но он кажется оптимизированным больше для «использования форума с рендерингом на сервере», чем для «headless-архитектуры, управляемой фронтендом».

Современные фреймворки (Next.js, Remix и др.) сильно выигрывают от:

  • меньшего количества круговых запросов;

  • более четких границ данных;

  • предсказуемых правил кэширования;

  • лучших агрегированных конечных точек.

Буду рад получить обратную связь от разработчиков или других участников, создающих headless-настройки Discourse.

Спасибо :folded_hands:

2

Ещё одна вещь, которую я заметил и которая меня раздражает: некоторые эндпоинты «защищены» с помощью кодирования форм вместо JSON, возможно, чтобы отпугнуть людей от вмешательства в API? Лучший пример — API отслеживания кликов по ссылкам. Я полагаю, это имеет смысл как защита, но любой всё равно может злоупотребить им, если действительно захочет, так что в итоге это просто усложняет разработчикам работу.