API Resourcesとは何ですか？

Question

Accepted Answer

**API Resources** は、Eloquent モデル（およびコレクション）がAPI レスポンスのために **JSON にシリアライズされる方法** を制御する変換クラスです。API の出力を正確に形成することができます — どのフィールドを公開するかを選択し、それらの名前を変更し、値をフォーマットし、関連データを含める — データベース構造から API 表現を分離します。

## 問題: 生のモデルを公開する

```php
// ❌ returning a model directly exposes ALL columns (maybe including sensitive ones)
return User::find($id);   // { id, name, email, password_hash, internal_notes, ... } 😱
```

## ソリューション: API Resource

```php
<?php
// php artisan make:resource UserResource
class UserResource extends JsonResource {
    public function toArray($request): array {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            // password and internal fields deliberately OMITTED
            'joined' => $this->created_at->toDateString(),   // format a value
            'is_admin' => (bool) $this->is_admin,
            // include related data (conditionally loaded)
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}
```

```php
// use it in a controller
return new UserResource($user);                  // a single model
return UserResource::collection(User::all());     // a collection
```

リソースの `toArray()` メソッドは、まさに JSON の形状を定義します — どのフィールドが表示されるかを制御し、それらの名前をリネームしてフォーマットし、関連リソースを含めます。機密フィールドは単に含まれません。

## 条件付きおよびネストされたデータ

```php
return [
    'id' => $this->id,
    'secret' => $this->when($request->user()->isAdmin(), $this->secret),  // conditional field
    'posts' => PostResource::collection($this->whenLoaded('posts')),       // only if eager-loaded
];
```

## なぜ重要なのか

API Resources は Laravel で設計の良い、安全な API を構築するために重要です — JSON 出力を正確に制御でき、これは **セキュリティ** と API 設計の両方にとって重要です。

最も重大な利点は **データ漏洩の防止** です: Eloquent モデルを直接返すと、そのすべてのカラムが公開されます（パスワードハッシュ、内部フラグ、またはその他の機密データを含む可能性があります — 深刻な脆弱性）、一方 API Resources では、公開するフィールドを明示的に選択でき、機密データがクライアントに到達することがないようになります。

セキュリティを超えて、API Resources は **API 表現をデータベーススキーマから分離する** ことで、クリーンな API 設計を可能にします — フィールドの名前を変更し、値をフォーマットし（日付、ブール値）、ネストされた/関連データを構造化し、権限に基づいて条件付きでフィールドを含めることができます。すべて専用の変換クラスで行うことができます。

これで、データベース内部の構造に結合されるのではなく、API コントラクトが安定して意図的なものになります。

API Resources — JSON 出力をどのように形成するか、明示的なフィールド制御のセキュリティ上の利点、条件付きフィールドおよびネストされたリソースなどの機能 — を理解することは、プロフェッショナルな Laravel API を構築するための重要な知識です。生のモデルを公開することはセキュリティ上も設計上も悪く、データ漏洩や出力がデータベースに厳密に結合されている API とは区別されるからです。

REST/JSON API は今日の Laravel の主要な用途であり、レスポンスの形状を（安全かつクリーンに）制御することは一般的で重要な必要性であるため、API Resources は、よく構築された安全な API とデータを漏洩させるか出力をデータベースに結合させている API とを区別する、頻繁に使用され、価値のあるツールです。