みなさんこんにちは 
Discourse をヘッドレスバックエンドとして使用したカスタムフロントエンド（Next.js ベースのアーキテクチャ）を構築しているのですが、実際の統合の観点から、現在の API 設計で直面している実用的なギャップをいくつか共有させていただきたく思います。
これは Discourse 自体への批判ではなく（Discourse はパワフルで柔軟です）、現代のフロントエンドと API 駆動型アーキテクチャにおける開発者体験（DX）を向上させるためのフィードバックです。
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がリアルタイムデータより遅れて更新されることがある -
キャッシュされたカウンターへの過度な依存
影響：
-
不正確な UI（特にダッシュボードや分析ページで顕著）
-
状態を検証するための追加の API 呼び出しが必要になる
提案：
-
「リアルタイム vs キャッシュ」のインジケーターやエンドポイントのバリエーションを追加する
-
または、カウントに関するウェッブフックやイベント駆動型の更新を提供する
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 システム
-
ヘッドレスアイデンティティプロバイダー
8. API キー：管理者キーとユーザーキー
ドキュメントでの明確化が必要：
以下の違い：
-
管理者 API キー
-
ユーザー API キー（
/admin/api/keysまたはユーザー API エンドポイント経由で作成）
質問点：
-
ライフサイクルと有効期限のルール
-
ユーザーごととグローバルな取り消しルール
-
種類ごとのセキュリティスコープの制限
これはプロダクショングレードの統合を構築する際に重要です。
最終的な考察
Discourse API はすでにパワフルですが、どちらかといえば「サーバーサイドレンダリングされたフォーラム利用」向けに最適化されており、「ヘッドレス/フロントエンド駆動型アーキテクチャ」向けには最適化されていないように感じられます。
現代のフレームワーク（Next.js、Remix など）は、以下の点から大きな恩恵を受けます：
-
ラウンドトリップの削減
-
明確なデータ境界
-
予測可能なキャッシュルール
-
より優れた集計エンドポイント
ヘッドレス Discourse 環境を構築しているメンテナーや他の開発者からのフィードバックをいただければ幸いです。
ありがとうございました 