メインコンテンツへスキップ

4. API 境界設計（インフラ層）

4.1 BookStack API の使用エンドポイント整理

本ツール（Book/Chapter/Page の骨格生成）で利用するエンドポイントは最小限に絞る。

一覧取得系（同一性判定・SKIP判定のための現状取得）

  • GET /api/books/{book_id}

    • Book直下の Page と Chapter の“並び”を content から取得する前提
    • 原則これ1本で足りる設計とし、追加の list 取得は増やさない

作成系（骨格生成の本体）

  • POST /api/chapters（Chapter作成）
  • POST /api/pages（Page作成：Book直下 / Chapter配下）

非対象（このプロジェクトでは使わない）

  • 更新（PUT/PATCH）、削除（DELETE）
  • 破壊操作をしない・再実行安全を優先するため

了解。こちらの理解ミスだった。 結論：BOOKSTACK_BASE_URL は「環境変数のみ」で扱う、で確定として CLI設計ドキュメントをきちんと修正した本文を出す。

以下は そのままBookStackに差し替え可能な形。

4.2 認証・ベースURLの扱い

本ツールでは、秘匿情報および環境依存の設定値をすべて環境変数から取得する。 CLI 引数や設定ファイルでの指定は行わない。

認証情報（必須）

    BookStack API の認証情報は 環境変数から取得する。 CLI 引数では受け取らない。
    環境変数 必須 説明 BOOKSTACK_TOKEN_ID 必須 API Token ID BOOKSTACK_TOKEN_SECRET 必須 API Token Secret

    認証情報は絶対にログや標準出力へ出力してはならない。 例外メッセージに含まれる可能性もあるため、出力時は必ずマスクまたは抑制する。

    API ベースURL

      BookStack API のベースURLは 環境変数から取得する。 CLI 引数による指定は行わない。
      環境変数 必須 説明 BOOKSTACK_BASE_URL 必須 BookStack API のベースURL

      正規化ルール

        末尾の / は トリムして保持する

        • TOKEN_ID https:/ TOKEN_SECRET は環境変数から取得する（秘匿情報のため）

        API ベースURL

          外部化する（環境変数 or CLI 引数）ことを基本とし、デフォルト値も持つ

          優先順位（高 → 低）

            CLI --base-url/example.com/ 環境変数 BOOKSTACK_BASE_URL デフォルト https://hiden-no-tare.example.com

            正規化ルール

              末尾の / はトリムして保持（https://.../ でも https://... でも同一扱い）は同一として扱う。

              ベースURLを環境変数に統一することで、 実行コマンドを固定したまま、環境（本番・検証・ローカル）を切り替えられる。

              CLI 引数を持たないことで、 実行方法が常に一意になり、運用・再実行時の混乱を防げる。

              4.3 クライアントクラスの責務定義

              インフラ層に BookStackClient（仮称）を置き、ユースケース層から HTTP 詳細を隠蔽する。

              共通責務

              • 認証ヘッダ付与（Authorization）
              • HTTP リクエスト送信・ステータスコード解釈
              • JSON の parse と “最小 DTO” への変換
              • リトライ（後述）

              一覧取得系

              • get_book_content(book_id) の提供

                • GET /api/books/{book_id} を呼び、Book直下の Page/Chapter と、Chapter配下の Page を再帰的に辿れる情報として返す
                • ユースケース層が「存在確認・同一性判定・SKIP判定」を行える材料のみ返す（下記の最小フィールド）

              作成系

              • create_chapter(book_id, name, ...) -> (id, name)

              • create_page(parent, name, markdown, ...) -> (id, name)

                • 親指定は parent_type / parent_id を入力とする（後述）
                • API送信直前に book_id or chapter_id に詰め替える責務はクライアント側に置く（ユースケースに漏らさない）

              4.4 API レスポンスの最小利用フィールド定義（id / name）

              手順書のとおり、ユースケース側が保持する参照（戻り値）は原則 id / name とする。

              • ChapterRef: id, name
              • PageRef: id, name

              ただし、同一性判定・構造把握のため、一覧取得時のみクライアント内部DTOとして追加フィールドを扱う（ユースケース側に “判定材料” として渡す用途）。

              一覧取得時の内部DTO（例）

              • type: page / chapter
              • id
              • name
              • parent_type: book / chapter
              • parent_id: 親オブジェクトID（Book ID または Chapter ID）
              • priority: 並び順を必要とする場合のみ（任意）

              4.5 親参照の表現（parent_type / parent_id）

              book_id / chapter_id のような “API都合の二重表現” をユースケース側に漏らさないため、親参照を以下で統一する。

              • parent_type: book または chapter（Enum相当で固定）
              • parent_id: 親オブジェクトの id

              マッピング規則（クライアント責務）:

              • parent_type == 'book' → POST /api/pages に book_id = parent_id
              • parent_type == 'chapter' → POST /api/pages に chapter_id = parent_id

              4.6 リトライロジックの配置（クライアント側）

              リトライは クライアント側（インフラ層） に実装し、ユースケース層は “成功/失敗” の結果のみ扱う。

              リトライ対象

              • ネットワーク例外（タイムアウト、接続失敗等）
              • HTTP 429（レート制限）
              • HTTP 5xx（サーバ側エラー）

              リトライしない

              • HTTP 4xx（429 を除く）

                • 入力不正・権限・存在しない等の可能性が高く、再試行しても改善しない前提

              バックオフ方針（固定値）

              • 最大試行回数：5回（初回 + リトライ4回）
              • 指数バックオフ（例）：0.5s → 1s → 2s → 4s → 8s（上限は適度にクリップ）
              • Retry-After が取れる場合はそれを優先（任意対応）
              上に戻る