はじめに

Day11 では
✅ HTTPステータスコードを正しく返す設計
を学びました。

今日はその続きとして、

✅ 「JSONレスポンスの中身をどう設計するのが正解なのか？」

を徹底的に解説します。

正直に言います。

❌ JSONレスポンスの設計がグチャグチャな API は
❌ フロントエンド開発が地獄になります。

今日でそれを完全に終わらせます。

今日のゴール

・成功・失敗で JSON を統一できるようになる

・一覧・詳細・作成・更新のレスポンス形式を揃えられる

・フロントエンドが「考えなくても」扱える API になる

・実務レベルのレスポンス設計ができるようになる

なぜ JSON レスポンス設計が重要なのか？

例えば、こんなレスポンスが混在していたらどうでしょう？

{ "result": "ok", "post": {...} }

{ "success": true, "data": {...} }

{ "status": "error", "msg": "失敗しました" }

フロント側は毎回こうなります。

if (res.result) { ... }
if (res.success) { ... }
if (res.status === 'error') { ... }

✅ 分岐地獄
✅ バグの温床

だからこそ JSON の形式は「全APIで統一」する必要があります。

結論：これが最強の JSON レスポンス設計

まずは これを全APIで固定してください。

成功時の基本フォーマット

{
  "status": "success",
  "data": {...}
}

失敗時の基本フォーマット

{
  "status": "error",
  "message": "エラーメッセージ"
}

たったこれだけです。
✅ これだけで フロント側が超書きやすくなります。

一覧取得（GET /posts）のレスポンス設計

{
  "status": "success",
  "data": [
    { "id": 1, "title": "最初の投稿" },
    { "id": 2, "title": "2つ目の投稿" }
  ]
}

✅ 配列は必ず data に入れる
✅ ページネーションも data を崩さずに追加できる

詳細取得（GET /posts/1）

{
  "status": "success",
  "data": {
    "id": 1,
    "title": "最初の投稿",
    "body": "本文です"
  }
}

✅ 一件でも必ず data に入れる
✅ 一覧と 構造を揃える

新規作成（POST /posts）

{
  "status": "success",
  "message": "投稿を作成しました",
  "data": {
    "id": 3,
    "title": "新しい投稿"
  }
}

✅ ユーザー向け文言 → message
✅ データ → data

更新（PUT /posts/1）

{
  "status": "success",
  "message": "投稿を更新しました",
  "data": {
    "id": 1,
    "title": "更新後タイトル"
  }
}

✅ 作成も更新も 構造は同じ

削除（DELETE /posts/1）

{
  "status": "success",
  "message": "投稿を削除しました"
}

✅ 削除後は data を返さなくてもOK

バリデーションエラー（400）

{
  "status": "error",
  "message": "タイトルは必須です"
}

認証エラー（401）

{
  "status": "error",
  "message": "ログインが必要です"
}

存在しないデータ（404）

{
  "status": "error",
  "message": "投稿が見つかりません"
}

サーバエラー（500）

{
  "status": "error",
  "message": "サーバ側で問題が発生しました"
}

Laravel で JSON フォーマットを統一する実装例

成功レスポンス

return response()->json([
  'status' => 'success',
  'data' => $post
], 200);

エラーレスポンス

return response()->json([
  'status' => 'error',
  'message' => '投稿が見つかりません'
], 404);

フロントエンド（React）側はこう書ける

fetch('/api/posts')
  .then(res => res.json())
  .then(json => {
    if (json.status === 'success') {
      setPosts(json.data);
    } else {
      alert(json.message);
    }
  });

✅ 成功でも失敗でも
✅ 同じ分岐ロジックがすべてのAPIで使い回せます

JSON 設計で初心者が必ずやるミス

APIごとにレスポンス構造が違う

{ "post": {...} }
{ "posts": [...] }
{ "item": {...} }

✅ 全部 data に統一する

エラーメッセージが配列だったり文字列だったりする

{ "message": ["必須です"] }
{ "message": "必須です" }

✅ メッセージの型も必ず揃える

ステータスと JSON の意味がズレている

HTTP 200
{
  "status": "error"
}

✅ HTTPステータスと JSON の意味は一致させる

今日のまとめ

・JSONレスポンスは 全APIで統一する

・成功：{ status: "success", data: ... }

・失敗：{ status: "error", message: "..." }

・一覧・詳細・作成・更新はすべて同じ構造でOK

・フロント側は status だけ見ればよくなる

・APIが「チームで使える設計」に進化する

次回 Day13 は…

「ミドルウェアでリクエストを加工する：認証・ログ・バリデーションの入口」

これでいよいよ
✅ 「誰が・いつ・どのリクエストを送ってきたのか」
を制御できるようになります。