Laravelで構築するRESTful API：基本設計から高度な実践例まで（壊れにくいAPIの作り方）

// routes/api.php
use App\Http\Controllers\Api\PostController;
use Illuminate\Support\Facades\Route;

Route::apiResource('posts', PostController::class);

Route::apiResource('posts', PostController::class)->only(['index', 'show']);

Route::apiResource('posts', PostController::class)->only(['index', 'show']);
// app/Http/Controllers/Api/PostController.php
namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\PostStoreRequest;
use App\Http\Requests\PostUpdateRequest;
use App\Http\Resources\PostResource;
use App\Models\Post;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;

class PostController extends Controller
{
    public function index(Request $request)
    {
        $query = Post::query()
            ->select(['id', 'user_id', 'title', 'status', 'published_at'])
            ->with(['user:id,name']);

        // フィルタ例
        if ($request->filled('status')) {
            $query->where('status', $request->string('status'));
        }

        // 検索例（雑なORでインデックスを潰しやすいので、実務では設計を揃える）
        if ($request->filled('q')) {
            $kw = $request->string('q');
            $query->where(function ($w) use ($kw) {
                $w->where('title', 'like', "%{$kw}%")
                  ->orWhere('body', 'like', "%{$kw}%");
            });
        }

        $perPage = min((int) $request->input('per_page', 20), 100);

        return PostResource::collection(
            $query->orderByDesc('published_at')->paginate($perPage)
        );
    }

    public function show(Post $post)
    {
        $post->load(['user:id,name']);

        return new PostResource($post);
    }

    public function store(PostStoreRequest $request)
    {
        $post = DB::transaction(function () use ($request) {
            return Post::create([
                'user_id' => $request->user()->id,
                'title' => $request->string('title'),
                'body' => $request->string('body'),
                'status' => $request->string('status', 'draft'),
                'published_at' => $request->input('published_at'),
            ]);
        });

        return (new PostResource($post))
            ->response()
            ->setStatusCode(201);
    }

    public function update(PostUpdateRequest $request, Post $post)
    {
        DB::transaction(function () use ($request, $post) {
            $post->fill($request->validated());
            $post->save();
        });

        return new PostResource($post->fresh()->load(['user:id,name']));
    }

    public function destroy(Post $post)
    {
        $post->delete();

        return response()->noContent();
    }
}

// app/Http/Requests/PostStoreRequest.php
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class PostStoreRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true; // 認可はPolicyで別途やる構成が多い
    }

    public function rules(): array
    {
        return [
            'title' => ['required', 'string', 'max:200'],
            'body' => ['required', 'string'],
            'status' => ['nullable', 'in:draft,public,private'],
            'published_at' => ['nullable', 'date'],
        ];
    }
}

// app/Http/Resources/PostResource.php
namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'status' => $this->status,
            'published_at' => $this->published_at,
            'user' => $this->whenLoaded('user', function () {
                return [
                    'id' => $this->user->id,
                    'name' => $this->user->name,
                ];
            }),
            'created_at' => $this->created_at,
            'updated_at' => $this->updated_at,
        ];
    }
}

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('posts', \App\Http\Controllers\Api\PostController::class);
});

// app/Policies/PostPolicy.php（例）
public function update(User $user, Post $post): bool
{
    return $user->id === $post->user_id;
}

// Controller側（例）
public function update(PostUpdateRequest $request, Post $post)
{
    $this->authorize('update', $post);

    // 更新処理...
}

// cursorPaginate例（次へ次へ型に向く）
$posts = Post::query()
    ->where('status', 'public')
    ->orderByDesc('published_at')
    ->cursorPaginate(20);

// 更新時にクライアントから "updated_at" を受け取り、条件に含める例
$affected = \App\Models\Post::query()
    ->whereKey($post->id)
    ->where('updated_at', $request->input('updated_at'))
    ->update([
        'title' => $request->input('title'),
        'body' => $request->input('body'),
    ]);

if ($affected === 0) {
    return response()->json([
        'message' => 'conflict',
        'detail' => 'The resource was updated by another request.'
    ], 409);
}

DB::transaction(function () use ($data, &$post) {
    $post = Post::create($data);
});

dispatch(new \App\Jobs\NotifyPostCreatedJob($post->id));

// withCountで関連件数をまとめる
$posts = Post::query()
    ->select(['id', 'user_id', 'title'])
    ->with('user:id,name')
    ->withCount('comments')
    ->latest()
    ->paginate(20);