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 引数）ことを基本とし、デフォルト値も持つ

  • 優先順位（高 → 低）

    1. CLI --base-url/example.com/
    2. 環境変数 BOOKSTACK_BASE_URL
    3. デフォルト 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 が取れる場合はそれを優先（任意対応）