APIレスポンス（JSON形式）

1. なぜ JSON レスポンスか

Laravel で API を設計する際は、クライアント側（SPA／モバイル／他サービス）が容易に解析できる形式として JSON が事実上の標準です。Laravel には配列・モデル・コレクションを自動的に JSON へ整形し、Content-Type: application/json ヘッダーを付与する仕組みが備わっています。laravel.com

2. 基本的な返し方

方法 記述例 補足
ヘルパ return response()->json(['message' => 'OK'], 200); 第 2 引数でステータスコード。
配列／コレクションを直接 return return ['id' => 1, 'name' => 'Foo']; shouldBeJson() により自動で JSON 化。laravel.io
Eloquent モデル return $user; モデル→JSON 変換時に リレーションは snake_case、隠し属性は $hidden で除外。laravel.com

3. ステータスコードとヘッダー

  • response()->json(..., 201) で 201 Created など適切なコードを明示。

  • 認証／認可エラーは abort(401) abort(403) で JSON を返すか、後述の例外ハンドラで統一。

  • CORS が必要な場合はミドルウェア（HandleCors など）で Access-Control-Allow-Origin を追加。

4. API リソースでの整形

php artisan make:resource UserResource で生成される JsonResource は、toArray() に定義したキーのみを JSON に含めるため、フィールド制御・リネーム・ネスト構造の統一に最適です。コレクションには UserResource::collection($users) を使用し、with() でメタ情報（success, version 等）を付与できます。laravel.com

メリット

  • コントローラがスリムになる

  • レスポンス構造の変更箇所が 1 か所に集約

  • テスト (assertJson) が単純化

5. ページネーションとリンク

paginate() と組み合わせると、リソースコレクションは自動で links, meta を含む JSON を生成します。これによりフロントエンドは current_page, last_page, per_page などを容易に取得可能です。laravel.com

6. エラーレスポンスの統一

シナリオ 推奨方法
バリデーション ValidationException は 422 で errors を含む JSON を自動生成。
その他例外 app/Exceptions/Handler.php 内 render() で expectsJson() 判定。また Laravel 11 以降は shouldRenderJsonWhen() で api/ に一致すれば常に JSON* と宣言できる。laravel-news.com
標準化 独自 ApiResponse ヘルパ／Macro を作り、success, data, message, errors の 4 つのキーに統一するプロジェクトも多い。medium.com

7. JSON 形式をさらに整える技法

  1. 数値の文字列化禁止：JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES オプションを response()->json($data, 200, [], JSON_UNESCAPED_UNICODE) のように追加。

  2. ゼロ詰め ID を維持したい場合は 文字列キャスト を行い、JS 側で桁落ちを防止。

  3. JSONP が必要なら ->withCallback($request->input('callback')) を併用（旧式ブラウザとの互換用）。laravel.com

8. コンテンツネゴシエーション

Accept: application/vnd.myapp.v2+json といった MIME を用いバージョン管理する場合、Route::middleware('accept.header:v2') などのカスタムミドルウェアで振り分ける方法が一般的です。

9. テストでの検証

php
$this->getJson('/api/users/1')
     ->assertOk()
     ->assertJsonPath('data.id', 1)
     ->assertJsonStructure([
         'data' => ['id', 'name', 'email'],
     ]);

sassertJsonFragment() で部分一致、assertExactJson() で完璧一致と、Laravel のテストアサーションは JSON レスポンス検証を豊富にサポートします。

10. まとめ

Laravel 11/12 系では **JsonResource と shouldRenderJsonWhen() を中心に「レスポンスの構造をコード上の 1 か所に閉じ込める設計」**がスタンダードになりました。これにより

  • メンテナンスコストの削減

  • バージョンアップ時の破壊的変更を局所化

  • クライアント実装への影響を最小化

が実現できます。まずは response()->json → JsonResource → 統一エラーフォーマット の順に導入し、プロジェクト全体で一貫性のある API レスポンスを設計してください。

ChatGPT4o 生成日：2025/06/23