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

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）
  • 破壊操作をしない・再実行安全を優先するため

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

正規化ルール

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

    • https://example.com/
    • https://example.com は同一として扱う。

ベース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 が取れる場合はそれを優先（任意対応）
上に戻る