概要

本アプリは読み取り専用で、独自のHTTP APIを公開しない。Server Componentからexternal/microcms/の関数を直接呼び、microCMSのREST APIへ接続する。

参考リポジトリのような/api/xxxのQuery/Command構成は採用しない。理由は次のとおり。

そこで本書では、次の2つを「API」として定義する。

  1. アプリ内部のデータ取得インターフェース（external/microcms/が提供する関数）
  2. 外部API（microCMS）の利用仕様（エンドポイント・パラメータ・環境変数）

1. 内部インターフェース（external/microcms/blogs.ts）

すべてQuery（副作用なし）。戻り値はアプリ内の型

関数 用途 引数 戻り値
getBlogList() 全記事の取得（トップ・一覧・サイドバー集計） なし（将来: limit offset） Article[]（公開日降順）
getBlogDetail(id) 記事1件の取得 id: string `Article
getProfile() 著者情報の取得（/profileと全ページのサイドバー著者カード） なし Author（profileはオブジェクト形式のためgetObjectで取得）
getAbout() このブログについての本文取得（/about） なし About（aboutはオブジェクト形式のためgetObjectで取得）
getPrivacyPolicy() / getDisclaimer() 規約系ページの本文取得（/privacy-policy・/disclaimer。それぞれ別ファイル） なし LegalPage（オブジェクト形式のためgetObjectで取得）

取得方針

項目 方針
取得タイミング Server Component内（ビルド時／リクエスト時）。クライアントから直接microCMSを呼ばない
全件取得 microCMSのlimit上限は100件。現状の記事数（6件程度）では全件を1回で取得する。100件を超えたらoffsetで繰り返し取得、またはサーバー側フィルタ（案B）へ移行する
ページネーション（表示件数・ページ番号） MVPではこの全件取得結果に対して**アプリ側（案A）**で絞り込み・ページ分割を計算する（05_domain_design.mdのpaginate）。1回のAPI呼び出しで取得できる上限（100件）を超える規模になったら、limit/offsetとfiltersをmicroCMSへ直接渡す案Bへ移行し、getBlogList()の引数を{ page, pageSize, category, q, month }相当に拡張する
集計 TOPICS・ARCHIVE・件数は取得済みの記事群から計算する（追加のAPI呼び出しをしない）
取得フィールド 一覧では本文（content）を除外して軽量化する（fieldsパラメータ）。詳細のみ本文を取得する
キャッシュ 更新頻度は低い前提。cacheLife("hours")程度（有効化は任意。判断は実装者）

2. microCMS API 利用仕様

エンドポイント

用途 メソッド URL 備考
記事一覧 GET https://{serviceDomain}.microcms.io/api/v1/blogs リスト形式のAPI
記事詳細 GET https://{serviceDomain}.microcms.io/api/v1/blogs/{contentId}
カテゴリ一覧（任意） GET .../api/v1/categories categoriesを独立コンテンツにした場合のみ
プロフィール GET .../api/v1/profile オブジェクト形式（1件のみ）。/profileと著者カードで使用
このブログについて GET .../api/v1/about オブジェクト形式（1件のみ）。/aboutの本文取得に使用

実際の呼び出しはmicrocms-js-sdk（getList / getListDetail）を使う。

記事一覧のクエリパラメータ

パラメータ 値の例 用途
orders -publishedAt 公開日の降順
limit 100 取得件数（既定10、最大100）
offset 0 取得開始位置（100件超で使用）
fields id,title,excerpt,categories,publishedAt 一覧では本文を除外
depth 1 カテゴリを参照コンテンツにした場合、参照先の中身まで展開する
filters title[contains]hooks サーバー側検索（案Bに移行する場合のみ）