PLANAV API エンドポイント設計書

基本情報

• ベースURL: https://api.planav.com/v1
• 認証: すべてのエンドポイントは、認証されたユーザーのみがアクセス可能です（/authエンドポイントを除く）
• レスポンス形式: JSON
• HTTP メソッド: GET, POST, PUT, DELETE

エンドポイント一覧

認証

エンドポイント	メソッド	説明
/auth/register	POST	新規ユーザー登録
/auth/login	POST	ユーザーログイン
/auth/logout	POST	ユーザーログアウト
/auth/refresh	POST	アクセストークンの更新
/auth/password/reset	POST	パスワードリセット要求
/auth/password/reset/confirm	POST	パスワードリセットの確認

ユーザー管理

エンドポイント	メソッド	説明
/users/me	GET	現在のユーザー情報を取得
/users/me	PUT	ユーザー情報を更新
/users/me/email	PUT	メールアドレスを変更
/users/me	DELETE	アカウントを削除

目標（Goals）管理

エンドポイント	メソッド	説明
/goals	POST	新しい目標を作成
/goals	GET	すべての目標を取得
/goals/[goal_id]	GET	特定の目標を取得
/goals/[goal_id]	PUT	目標を更新
/goals/[goal_id]	DELETE	目標を削除
/goals/[goal_id]/archive	POST	目標をアーカイブ
/goals/search	GET	目標を検索
/goals/categories	GET	目標カテゴリを取得

デイリータスク管理

エンドポイント	メソッド	説明
/tasks	POST	新しいタスクを作成
/tasks	GET	すべてのタスクを取得
/tasks/[task_id]	GET	特定のタスクを取得
/tasks/[task_id]	PUT	タスクを更新
/tasks/[task_id]	DELETE	タスクを削除
/tasks/goal/[goal_id]	GET	特定の目標に関連するすべてのタスクを取得
/tasks/date/[date]	GET	特定の日付のタスクを取得

進捗管理

エンドポイント	メソッド	説明
/progress/goals/[goal_id]	GET	特定の目標の進捗状況を取得
/progress/overall	GET	全体の目標達成率を取得
/progress/categories	GET	カテゴリ別進捗状況を取得
/progress/trends	GET	進捗トレンドを取得

通知

エンドポイント	メソッド	説明
/notifications	GET	すべての通知を取得
/notifications/[notification_id]	PUT	通知を既読にマーク
/notifications/settings	GET	通知設定を取得
/notifications/settings	PUT	通知設定を更新

データバックアップと復元

エンドポイント	メソッド	説明
/backups	POST	バックアップを作成
/backups	GET	バックアップリストを取得
/backups/[backup_id]	GET	特定のバックアップを取得
/backups/[backup_id]/restore	POST	バックアップから復元

その他

エンドポイント	メソッド	説明
/settings	GET	ユーザー設定を取得
/settings	PUT	ユーザー設定を更新

リクエスト/レスポンス例

目標作成 (POST /goals)

リクエスト:

{
  "name": "マラソン完走",
  "category": "健康",
  "icon": "running",
  "color": "#FF5733",
  "deadline": "2024-12-31",
  "extend": false,
  "unit": "km",
  "total": 42.2,
  "allocation": 10
}

レスポンス:

{
  "id": 1,
  "name": "マラソン完走",
  "category": "健康",
  "icon": "running",
  "color": "#FF5733",
  "deadline": "2024-12-31",
  "extend": false,
  "unit": "km",
  "total": 42.2,
  "allocation": 10,
  "created_at": "2024-07-06T10:00:00Z"
}

タスク取得 (GET /tasks/goal/[goal_id])

レスポンス:

{
  "tasks": [
    {
      "id": 1,
      "goal_id": 1,
      "date": "2024-07-06",
      "amount": 5.5,
      "note": "朝のランニング",
      "status": "completed",
      "difficulty": "medium",
      "estimated_time": 60
    },
    {
      "id": 2,
      "goal_id": 1,
      "date": "2024-07-07",
      "amount": 6.0,
      "note": "夕方のランニング",
      "status": "not_started",
      "difficulty": "hard",
      "estimated_time": 70
    }
  ]
}

エラーレスポンス

エラーが発生した場合、APIは適切なHTTPステータスコードと共に以下の形式でエラー情報を返します：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "エラーの詳細メッセージ"
  }
}