Cycle Journal

Appearance

API設計 ​

API仕様の正式な定義は docs/api/openapi.yaml を参照。ここでは設計方針とルールを記載する。

設計方針 ​

項目方針
スタイルREST
バージョニングなし（後方互換性を維持、破壊的変更時は新エンドポイント追加）
認証Sign in with Apple JWT → FastAPI ミドルウェアで検証
仕様書OpenAPI 3.0 (openapi.yamlが単一の真実)

なぜRESTか ​

GraphQLは個人プロジェクトのスコープではオーバー。Cloud RunでシンプルにHTTPを受けてOpenAPIで仕様を定義しやすい。

命名規則 ​

  • リソース名: 複数形・小文字（/sessions, /tasks）
  • フィールド名: snake_case
  • 日時: ISO 8601 UTC（2024-01-01T00:00:00Z）

レスポンス形式 ​

json
// 成功時
{ "data": { ... } }

// エラー時
{
  "error": {
    "code": "ValidationError",
    "message": "The request body is invalid.",
    "details": [{ "field": "content", "message": "content is required" }]
  }
}

HTTPステータスコード ​

コード用途
200成功 (GET, PUT, PATCH)
201作成成功 (POST)
204成功・レスポンスなし (DELETE)
400リクエスト不正
401認証エラー
403認可エラー
404リソースなし
422バリデーションエラー
429レート制限超過
500サーバーエラー

認証フロー ​

1. iOS: Sign in with Apple で identityToken 取得
2. iOS → API: Authorization: Bearer {identityToken}
3. FastAPI ミドルウェア: Apple公開鍵でJWT検証
4. 検証OK → ルーターハンドラ実行

エンドポイント一覧 ​

MethodPath説明
GET/healthヘルスチェック
POST/auth/verifyApple IDトークン検証
POST/coachコーチとの会話
GET/sessionsセッション一覧
POST/sessionsセッション作成
GET/sessions/{session_id}セッション詳細
DELETE/sessions/{session_id}セッション削除
GET/tasksタスク一覧
POST/tasksタスク作成
PUT/tasks/{task_id}タスク更新
DELETE/tasks/{task_id}タスク削除
POST/tasks/{task_id}/reflectionふりかえり登録
GET/users/me自分のユーザー情報

コーチ応答メタデータ ​

POST /coach のレスポンスには以下のメタデータが含まれる:

json
{
  "data": {
    "message": "コーチの応答テキスト",
    "session_id": "xxx",
    "metadata": {
      "stage": "dev",
      "model": "claude-sonnet-4-20250514",
      "cycle_element": "Root",
      "detected_emotion": "不安",
      "response_type": null
    }
  }
}
フィールド説明LangGraph OFFLangGraph ON
cycle_elementCycleモデル要素リクエスト指定値のみAI判定結果
detected_emotion検出された感情nullAI判定結果（1単語）

LangGraphフローの有効/無効は環境変数 USE_LANGGRAPH で切り替え。

ログ ​

Cloud Logging に構造化JSONで出力:

json
{
  "timestamp": "2024-01-01T00:00:00Z",
  "severity": "INFO",
  "request_id": "xxx",
  "user_id": "xxx",
  "message": "..."
}