第06回: API Resourceとレスポンス統一 — JSONの形式は「Controller」ではなく「Resource」が決める

(Updated: )
1 min read

章: 第2章: Web層の実践設計

APIレスポンスの形式がエンドポイントごとに微妙に差い、フロントエンドの頓いが増える――この問題は、レスポンス整形ロジックが Controllerやモデルに散らばっている ことから生まれます。

LaravelのAPI Resourceは、レスポンス形式を 専用の変換層 に集約する仕組みです。実体のプロパティが変更されてもAPIコントラクトは守りやすくなり、内部実装の変化を外部に漏らしにくくなります。

なぜAPI Resourceが重要なのか

json() や $model->toArray() をControllerで直接返すと次の問題が起きます。

  • DBカラム名がそのまま外部に漏れる（安全リスク）
  • 関連データの形式がエンドポイントごとに差い、履歴がない
  • created_at の形式が統一されず、クライアントが迫られる

チェックポイント: Resourceでもっとも大切なのは「何を返さないか」。不要なフィールドを含めないことがセキュリティとパフォーマンスの両方に宇宙ます。

Controllerに直書き vs API Resource

観点 toArray()直接返却 API Resource
DBカラム名の露出 容易に実際のカラム名が漏れる toArray()でマッピングして防ぐ
レスポンス形式の統一 分散しがち 一箇所で管理
負荷計算 Eager loading必須 when()で条件付きに含める
テストの書きやすさ 低い assertJson()で確実に検証可能

実装例


<?php
use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'author' => [
                'id' => $this->user_id,
                'name' => $this->user?->name,
            ],
            'created_at' => $this->created_at?->toIso8601String(),
        ];
    }
}

まとめ & 次のステップ

  • API ResourceはモデルとAPIコントラクトの間の変換層―内部実装を外部に防ぐ
  • toArray() で定義したフィールドだけが返るため、セキュリティリスクを下げられる
  • ResourceCollection で一覧形式も統一し、meta 等のページネーション情報も一箇所で管理できる
  • Controllerは return new PostResource($post) の1行になり、責務が清潔になる

次回は 第07回: Eloquent最適化（N+1/集計） で、一覧画面のクエリ性能を大幅に改善する手法を学びます。

Related Articles