laravel-api

Laravel を使用した RESTful API の構築を扱います。API リソースによるレスポンス変換、Sanctum 認証、レート制限、ルートのバージョニング、Form Request によるバリデーション、ページネーション（オフセット／カーソル）、HTTP クライアントを介した外部 API の利用を網羅します。（スパースフィールドセット、インクルード、リンクに対応した）JSON:API 仕様準拠のエンドポイントについては、代わりに laravel-jsonapi を参照してください。

Laravel API 開発

エージェントのワークフロー（必須）

実装の前に、必ず 3 つのエージェントを並列で起動してください。それぞれ name を指定して、Agent を 1 回ずつ呼び出します。

1. fuse-ai-pilot:explore-codebase - 既存の API パターンを分析します
2. fuse-ai-pilot:research-expert - Context7 を使って Laravel の API ドキュメントを確認します
3. mcp__context7__query-docs - API リソースと Sanctum のパターンを確認します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

Laravel で API リソースを使用してレスポンスを変換し、Sanctum で認証する RESTful API を構築します。

コンポーネント	目的
コントローラー	リクエストを処理し、サービスに委譲します
Form Request	入力を検証し、アクションを認可します
API リソース	モデルを JSON に変換します
ミドルウェア	認証、レート制限、CORS
ルート	グループ化されたバージョン管理済みエンドポイント
ページネーション	オフセット／カーソルページネーション
HTTP クライアント	外部 API を利用します

---

重要なルール

1. 常に API リソースを使用する - Eloquent モデルを直接返さないでください
2. ルートをバージョン管理する - /v1/、/v2/ をプレフィックスとして付けます
3. すべての入力を検証する - インラインバリデーションではなく、Form Request を使用します
4. レート制限 - ルートごとに制限を設定します
5. 一貫性のあるレスポンス - 同じ構造と適切なステータスコードを使用します
6. サービスを使用する - コントローラーを薄く保ちます
7. Eager Load する - ページネーションの前に with() を使い、N+1 を防ぎます

---

リファレンスガイド

コアコンセプト

トピック	リファレンス	参照するタイミング
ルーティング	routing.md	バージョン管理された API ルートの定義
コントローラー	controllers.md	コントローラーパターン、リソースメソッド
ミドルウェア	middleware.md	ルートの保護、リクエストのフィルタリング
バリデーション	validation.md	Form Request、バリデーションルール

リクエスト／レスポンス

トピック	リファレンス	参照するタイミング
リクエスト	requests.md	入力、ファイル、ヘッダーへのアクセス
レスポンス	responses.md	API リソース、ステータスコード
ページネーション	pagination.md	オフセット／カーソルページネーション

高度なトピック

トピック	リファレンス	参照するタイミング
レート制限	rate-limiting.md	スロットル設定
HTTP クライアント	http-client.md	外部 API の利用
URL	urls.md	URL の生成、署名付き URL
文字列	strings.md	文字列ヘルパー、UUID、スラッグ
リダイレクト	redirects.md	リダイレクトレスポンス

---

テンプレート（コード例）

コントローラーとルート

テンプレート	目的
ApiController.php.md	サービスを含む CRUD コントローラー一式
api-routes.md	ミドルウェアを含むバージョン管理済みルート
routing-examples.md	詳細なルーティングパターン

バリデーションとリソース

テンプレート	目的
FormRequest.php.md	Store／Update Form Request
validation-rules.md	すべてのバリデーションルールのリファレンス
ApiResource.php.md	リレーションシップを含むリソース

外部 API

テンプレート	目的
HttpClientService.php.md	再利用可能な HTTP クライアントサービス

---

クイックリファレンス

リソースのレスポンス

return PostResource::collection($posts);
return PostResource::make($post);

ステータスコード

return PostResource::make($post)->response()->setStatusCode(201);
return response()->json(null, 204);

フォームリクエスト

public function store(StorePostRequest $request): JsonResponse
{
    $post = $this->service->create($request->validated());
    return PostResource::make($post)->response()->setStatusCode(201);
}

レート制限

Route::middleware('throttle:60,1')->group(fn () => ...);

バージョン付きルート

Route::prefix('v1')->group(function () {
    Route::apiResource('posts', PostController::class);
});

ページネーション

return PostResource::collection(Post::paginate(15));

---

機能一覧

機能	状態	リファレンス
RESTful コントローラー	✅	controllers.md
API リソース	✅	responses.md
フォームリクエストのバリデーション	✅	validation.md
ルートのバージョン管理	✅	routing.md
ルートモデルバインディング	✅	routing.md
ミドルウェア	✅	middleware.md
レート制限	✅	rate-limiting.md
ページネーション	✅	pagination.md
カーソルページネーション	✅	pagination.md
HTTP クライアント	✅	http-client.md
署名付き URL	✅	urls.md
JSON レスポンス	✅	responses.md

---

Laravel 13 に関する注意事項

API リソースの属性

Laravel 13 では、PHP 属性を使用して ResourceCollection を設定するための #[Collects] と #[PreserveKeys] が導入されています。

use Illuminate\Http\Resources\Json\ResourceCollection;
use Illuminate\Http\Resources\Attributes\Collects;
use Illuminate\Http\Resources\Attributes\PreserveKeys;

#[Collects(PostResource::class)]
#[PreserveKeys]
final class PostCollection extends ResourceCollection {}

JSON:API 準拠

JSON:API API（スパースフィールドセット、インクルード、リンク）については、?include=、?fields[type]=、仕様に準拠したページネーションを扱う [[laravel-jsonapi]] を参照してください。

ベストプラクティス

実施すること

• すべての公開 JSON レスポンスに API リソース（JsonResource）を使用する
• ヘッダーではなく URL（/api/v1）でバージョン管理する（可読性が高く、キャッシュ可能です）
• ユーザーごと、かつ IP ごとにレート制限する（throttle:60,1 ＋ カスタムリミッター）
• エンドポイントを実装する前に OpenAPI/Scribe でドキュメントを作成する
• 大きなリストには cursor() ページネーションを優先する（安定しており、高パフォーマンスです）

実施しないこと

• Eloquent モデルを直接返さない（機密性の高いカラムが漏えいします）
• HTTP ステータスを混同しない（バリデーションには常に 422 を使用し、401 と 403 を使い分けます）
• フォームリクエストのバリデーションを省略しない（コントローラー内では決してバリデーションしません）
• 自動採番 ID を公開しない（UUID/ULID を優先します）
• 外部 Webhook 用の PreventRequestForgery の例外設定を忘れない