LaravelでAPIを作ってみよう！初心者でもできるRESTful設計の基本

CRUDって何？って思った人はこの下の記事で説明していますので、一度読みに行っていただけるとRESTful APIとCRUDの関係理解がより深まります。

はじめに準備するもの

• PHP 8.x がインストールされた環境
• Composer
• Laravel12
• エディタ（VSCode など）
• Postman やcurl でAPIを叩く環境

まずはローカルにLaravelのプロジェクトを作成しましょう。コマンドは次の通りです。

composer create-project laravel/laravel laravel-api-sample
cd laravel-api-sample
php artisan serve

まだLaravelの開発環境が出来てないよ！という方は下の記事にて説明していますので合わせてご覧ください。

🧱 ステップ1: モデルとデータベース構造の定義

RESTful APIのデータ処理の中心となるのが、Eloquentモデルとデータベースです。Laravelでは、これらをArtisanコマンドとマイグレーションファイルを使って定義します。今回はシンプルなブログ記事（Article）というリソースを作成します。

1. モデルの作成と設定

Artisanコマンドを使って、Articleモデルを作成します。ここで-mオプションを付与することで、モデルと同時に対応するマイグレーションファイルも自動で生成されるため、作業が一気に効率化されます。

$ php artisan make:model Article −m

生成されたモデルファイル（app/Models/Article.php）には、マスアサインメント（一括代入）を防ぐための$fillableプロパティを定義します。これは、悪意のあるユーザーが意図しないカラムにデータを書き込むのを防ぐためのセキュリティ対策として非常に重要です。ここでは、titleとbodyのみを書き込み可能とします。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Article extends Model {
    /
     * 一括割り当て可能な属性。
     * @var array
     */
    protected $fillable = ['title', 'body'];
}

2. マイグレーションファイルの編集と実行

次に、データベースに記事を保存するためのテーブル構造を定義します。生成されたマイグレーションファイル（database/migrations/xxxx_create_articles_table.php）を編集し、titleとbodyカラムを追加します。

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateArticlesTable extends Migration {
    /
     * マイグレーションを実行する（テーブルを作成する）。
     * @return void
     */
    public function up(): void {
        Schema::create('articles', function (Blueprint $table) {
            $table->id(); // 主キーとしてオートインクリメントID
            $table->string('title'); // 記事のタイトル (短めの文字列)
            $table->text('body'); // 記事の本文 (長めのテキスト)
            $table->timestamps(); // created_atとupdated_atカラムを自動追加
        });
    }

    /
     * マイグレーションを元に戻す（テーブルを削除する）。
     * @return void
     */
    public function down(): void {
        Schema::dropIfExists('articles');
    }
}

ファイルの編集後、Artisanコマンドを実行して、データベースにこのテーブルを実際に作成します。

$ php artisan migrate

このコマンドが成功すれば、データベースの準備は完了です。これで、Laravelが持つ強力なEloquent ORMを使って、データをオブジェクトとして簡単に操作できるようになります。

⚙ステップ2: コントローラーの作成

RESTful APIの中心となるのがコントローラーです。ここでは、ArticleControllerを作成し、記事の一覧取得・作成・表示・更新・削除といった基本的な操作を実装します。

$ php artisan make:controller ArticleController −−api

このコマンドで、API専用のコントローラーが生成されます。以下はその実装例です。

<?php

namespace App\Http\Controllers;

use App\Models\Article;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class ArticleController extends Controller {
    public function index(): JsonResponse {
        $articles = Article::all();
        return response()->json($articles);
    }

    public function store(Request $request): JsonResponse {
        $validated = $request->validate([
            'title' => 'required|string|max:255',
            'body' => 'required|string',
        ]);

        $article = Article::create($validated);

        return response()->json($article, 201);
    }

    public function show(int $id): JsonResponse {
        $article = Article::find($id);

        if (!$article) {
            return response()->json(['error' => 'Article not found'], 404);
        }

        return response()->json($article);
    }

    public function update(Request $request, int $id): JsonResponse {
        $article = Article::find($id);

        if (!$article) {
            return response()->json(['error' => 'Article not found'], 404);
        }

        $validated = $request->validate([
            'title' => 'sometimes|required|string|max:255',
            'body' => 'sometimes|required|string',
        ]);

        $article->update($validated);

        return response()->json($article);
    }

    public function destroy(int $id): JsonResponse {
        $article = Article::find($id);

        if (!$article) {
            return response()->json(['error' => 'Article not found'], 404);
        }

        $article->delete();

        return response()->json(['message' => 'Deleted successfully']);
    }
}

このように、各メソッドではバリデーションやエラーハンドリングを丁寧に行うことで、APIの信頼性と使いやすさが向上します。特に初心者の方は、バリデーションとレスポンスの形式に注意して実装すると良いでしょう。

🔗 ステップ3: LaravelにおけるRESTful APIルーティングの設定

LaravelでAPIを構築する上で最も重要なステップが、ルーティングの設定です。これは「どのURLに、どのHTTPメソッド（GET, POSTなど）でアクセスが来たら、どのコントローラーのどのメソッドを実行するか」という交通整理の役割を果たします。Laravel 12以降では、ルーティングの管理方法に大きな変更があったため、以前のバージョンに慣れている方も、ここで最新の手順を確認しておく必要があります。

Laravel 12以降の新しいアプリケーション構造では、従来の routes/api.php ファイルがデフォルトで自動的に含まれていません。RESTful APIを構築するには、開発者が意図的にルートファイルを作成し、アプリケーションのコア設定ファイルである bootstrap/app.php に明示的に読み込ませる必要があります。

1. APIルートファイルの作成と定義

まずはAPIのルーティングを記述するためのファイルを作成します。ファイル名は慣習に従い、routes/api.php とします。

$ touch routes/api.php

次に、作成したファイルにRoute::apiResourceを使ってルーティングを定義します。これは、RESTful APIに必要なルートを一括で定義するためのLaravelの便利な機能です。

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ArticleController;

// 'articles'というリソースに対して、RESTfulなCRUD操作に対応するルートを一括定義
Route::apiResource('articles', ArticleController::class);

この一行で、ArticleController のメソッドに紐づく、完全なRESTful APIのエンドポイントが定義されます。

2. bootstrap/app.php でルートファイルを読み込む

Laravel 12以降では、ルートファイルの読み込みをApplication::configure() メソッド内で一元管理するようになりました。生成した routes/api.php ファイルがLaravelアプリケーションに認識されるように、bootstrap/app.php を編集します。

<?php

use Illuminate\Foundation\Application;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php', // <<< ここを明示的に追加
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )->withMiddleware(...); // その他の設定は省略

このように、api: __DIR__.'/../routes/api.php' を追記することで、Laravelはあなたが定義したAPIルートを正しくロードするようになります。

3. ルーティングの動作確認：生成されたエンドポイント

上記の設定により、アプリケーションには以下の標準的なRESTful APIエンドポイントが自動的に生成されます。ルートはすべて /api のプレフィックスが付き、ArticleController の対応するメソッドにマッピングされます。

❓ APIのルーティング設定に関する疑問

Q. なぜLaravelでは api.php が最初から存在しないのですか？

A. Laravel12以降では、アプリケーションのルーティング構造がよりモジュール化され、開発者が意図的に必要なルートファイルのみを読み込む設計に変わりました。これにより、WebアプリケーションとしてAPIを使わないプロジェクトの起動オーバーヘッドを減らし、ルートファイルの管理をより明確にすることが目的です。APIが必要な場合は、上記のように明示的に追加し、読み込ませる手順が必要になります。

Q. web.php にAPIルートを書いても機能しますか？

A. 技術的には書くことは可能で、機能します。しかし、構造を分けることが強く推奨されます。 routes/api.php で定義されたルートは、デフォルトで認証やレート制限などのAPIに特化したミドルウェアグループが適用されることが想定されています。web.php はセッションベースの認証を前提とするため、両者を分けることで、セキュリティと保守性が向上し、将来的なAPIの拡張も容易になります。

Q. Route::apiResource() とは何ですか？普通の Route::resource() と何が違いますか？

A. Route::apiResource() は、RESTfulなルートを一括で定義するためのLaravelの便利なメソッドです。これは、APIで通常使用しないセッションやビューに関連するメソッド（create や edit など）を除外してルートを生成します。これにより、API開発に必要な最小限の5つのルート（index, store, show, update, destroy）のみを定義でき、コントローラーの無駄なメソッド定義を避けられます。

⏰ ステップ4: LaravelのRESTful APIをcurlでテストする方法

Laravelで構築したRESTful APIは、curlコマンドを使って簡単に動作確認できます。ここでは、基本的なCRUD操作をcurlでテストする方法を紹介します。

記事一覧の取得（GET）

$ curl -X GET http://localhost:8000/api/articles

記事の作成（POST）

$ curl -X POST http://localhost:8000/api/articles \
-H "Content-Type: application/json" \
-d '{"title":"はじめてのAPI","body":"LaravelでRESTful APIを作ってみました"}'

特定の記事の取得（GET）

$ curl -X GET http://localhost:8000/api/articles/1

記事の更新（PUT）

$ curl -X PUT http://localhost:8000/api/articles/1 \
-H "Content-Type: application/json" \
-d '{"title":"API更新","body":"内容を更新しました"}'

記事の削除（DELETE）

$ curl -X DELETE http://localhost:8000/api/articles/1

curlはコマンドラインから直接APIの挙動を確認できるため、開発初期の動作確認やCI/CDのテストにも活用できます。

よくある疑問

Q. curlがコマンドとして使えない場合は？

A. Windowsの場合はGit BashやWSL、MacやLinuxではターミナルで利用できます。curlがインストールされていない場合は、公式サイトから導入してください。

Q. JSONの書き方が分からない

A. -d オプションで送るデータは、{"キー":"値"} の形式で記述します。複数のフィールドを送る場合はカンマで区切ります。

Q. LaravelのAPIがうまく動かない

A. php artisan serve でサーバーが起動しているか、ルーティングやコントローラーが正しく設定されているか確認しましょう。エラーメッセージが表示される場合は、内容をよく読み取って対応します。

🚨 LaravelでRESTful APIが動かないときの具体的対処方法

LaravelでAPIを構築する際、エラーが発生すると初心者は特にパニックになりがちです。しかし、ほとんどのトラブルは、「ルートの読み込み」「データバリデーション」「キャッシュの問題」といった、特定のパターンに分類されます。ここでは、LaravelでAPIを構築する際によく遭遇する問題と、その具体的な解決手順を紹介します。

1. ルートが全く反応せず404エラーになる（ルート設定の問題）

Laravelでは、routes/api.php を作成しただけでは、アプリケーションはそれを自動的に読み込みません。これが、APIにアクセスした際に「404 Not Found」になる最も一般的な原因です。

対処法: アプリケーションのコア設定ファイルである bootstrap/app.php にて、APIルートを明示的に指定して読み込ませる必要があります。

<?php

use Illuminate\Foundation\Application;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php', // <<< ここを追記
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    );

確認: ターミナルで php artisan route:list を実行し、定義したAPIルートがリストに含まれているか確認してください。含まれていなければ、読み込み設定が失敗しています。

2. POST/PUTリクエストでデータが保存されない（バリデーションと入力の問題）

POSTやPUTでデータを送信しても、期待通りにデータベースに保存されない場合、データがコントローラーに正しく届いていないか、Laravelのバリデーションで弾かれている可能性が高いです。

また、Controllerメソッド内でバリデーションを行ってください。これがないと、データベースの制約違反（例：NOT NULL違反）などで予期せぬエラーが発生します。

<?php

use Illuminate\Http\Request;

public function store(Request $request) {
    // 送信されたデータの検証（Validation）
    $validated = $request->validate([
        'title' => 'required|string|max:255',
        'body' => 'required|string',
    ]);

    // バリデーションを通過したデータのみを使って保存
    return Article::create($validated);
}

3. マイグレーション実行後もテーブルが存在しない（キャッシュとDB接続の問題）

php artisan migrate を実行したのに、モデルを操作しようとすると「テーブルが見つからない」エラー（Table not found）が出る場合、PHPやLaravelの設定キャッシュ、または古いデータベース接続情報が残っている可能性があります。

対処法: 特に環境変数（.env）を変更した後や、マイグレーションファイルを追加した後に発生しやすいため、以下のコマンドを順に実行してキャッシュをクリアし、DB接続情報をリフレッシュしてください。

$ php artisan config:clear
$ php artisan cache:clear
$ php artisan route:clear

$ php artisan migrate:fresh --seed # 既存のテーブルを全削除し、再作成（データも消えるので注意）

4. データは送信できているのにデータベースに保存されない（Eloquentモデルの問題）

バリデーションを通過しても、Article::create()などが機能せず、エラーになる場合、ほとんどの場合マスアサインメント脆弱性を防ぐための設定が漏れています。

対処法: Eloquentモデル（app/Models/Article.phpなど）で、$fillableプロパティに、リクエストから一括代入を許可するカラム名を明示的に設定してください。

<?php

use Illuminate\Database\Eloquent\Model;

class Article extends Model {
    /
     * 一括割り当て可能な属性。
     * @var array
     */
    protected $fillable = ['title', 'body'];
}

5. APIにアクセスしてもブラウザで何も表示されない（レスポンス形式の問題）

コントローラーの処理は成功しているのに、ブラウザで確認すると真っ白になる、または予期せぬ表示になることがあります。これは、APIが返すデータ形式がブラウザでレンダリングできるHTML形式ではないためです。

対処法: APIのコントローラーメソッドでは、必ずJSON形式でレスポンスを返すように明示的に指定します。

<?php

use App\Models\Article;

public function show(Article $article) {
    // LaravelはEloquentモデルを返すと自動的にJSONに変換してくれるが、
    // 明示的に response()−>json() を使う方がAPIとしては安全で明確
    return response()−>json($article, 200);
}
        

❓デバッグのヒント

Q. LaravelのAPIが404になるのは、ルート設定以外に何が原因ですか？

A. ルートが正しく設定されている場合でも、URLのプレフィックスを忘れている可能性があります。apiResource()などで定義されたルートは、デフォルトで /api/ のプレフィックスが必要です。例えば、Route::apiResource('articles', ...) は、/articles ではなく /api/articles でアクセスする必要があります。

Q. データベースのエラーなど、エラーの詳細を確認したい

A. Laravelはすべての重要なエラーを storage/logs/laravel.log ファイルに記録しています。エラーが発生したら、まずこのファイルをチェックすることで、SQLの構文エラーやPHPの致命的なエラーなど、具体的な原因を特定できます。開発中は、.env の APP_DEBUG=true に設定しておくと、ブラウザにも詳細なエラーが表示されます。

Q. POSTリクエストがうまくいかない（特にPUT/PATCH）

A. POSTリクエストが失敗する場合、ヘッダーに Content-Type: application/json がないか、あるいはCSRFトークンが必要です。APIの場合はCSRFは不要ですが、Webルートで試行している場合はCSRFトークンがないと419エラー（Page Expired）になります。PUT/PATCHの場合は、HTMLフォームでは直接送信できないため、隠しフィールドを使うか、APIクライアント（Postmanなど）で正しくメソッドを指定する必要があります。

🚀 実務目線のちょっと上級ポイント：APIを「本番レベル」に引き上げる要素

RESTful APIの基本機能（CRUD）が完成したら、次は実務や本番環境で必須となる品質・セキュリティ・保守性を高めるための要素を取り入れることを検討しましょう。これらの要素は、単に機能を追加するだけでなく、APIをより堅牢で、将来の変更に強い構造へと進化させます。若手エンジニアは、これらの視点を持つことで、コードレビューや設計段階で一歩進んだ提案ができるようになります。

以下は、API開発を次のレベルへ引き上げ、ビジネスの変化に対応するために重要な、上級者向けの考慮事項です。

• レスポンスのバージョン管理（例：/api/v1/posts）を早めに考える

  APIを公開した後、一度決めたレスポンス形式（JSONの構造）を変更するのは非常に困難です。互換性を維持しながら機能を追加・修正するために、URLにバージョン情報（例：/api/v1/posts, /api/v2/posts）を含める設計を早い段階で確立しておくことが、APIの寿命を延ばす鍵となります。

• Rate Limiting（レート制限）でDoS対策を行う

  APIは外部からの大量アクセスに晒されます。悪意のある攻撃（DoS攻撃）や、単なるクライアント側のバグによる過剰なリクエストからサーバーを保護するために、レート制限（特定の時間内に許可するリクエストの上限設定）は必須のセキュリティ対策です。Laravelのミドルウェア機能を使えば、簡単に実装できます。

• ログ・監視（Laravel Telescopeや外部サービス）を導入する

  本番環境で何らかの異常やエラーが発生した際、その原因を迅速に特定できるかどうかが、ビジネスへの影響度を左右します。Laravel TelescopeやSentryなどの外部監視サービスを導入し、APIの実行時間、データベースクエリ、エラーの内容などを詳細に記録し、常に監視できる体制を構築しておく必要があります。

• DTOやサービス層を導入してコントローラを薄くする（薄いコントローラ原則）

  ビジネスロジックをすべてコントローラー（Controller）に書いてしまうと、コードが長大になり、テストや再利用が困難になります（通称「太ったコントローラー」）。これを避けるため、DTO (Data Transfer Object) で入力データを整形し、サービス層（Service Layer） に複雑なビジネスロジックを分離することで、コントローラーをシンプルに保ち、保守性を劇的に向上させます。

❓ LaravelでRESTful APIを構築する際によくある初心者向けFAQ（トラブルシューティング集）

LaravelのAPI開発で初心者がつまずきやすいポイントと、その実用的な解決策をまとめました。エラーに遭遇した際は、まずここを確認してください。

Q. Laravel12以降では routes/api.php が見つかりません。どうすれば良いですか？

A. Laravel 12の新しいアプリケーション構造では、ルートファイルの読み込みが明示的な設定になりました。routes/api.php は自分で作成する必要があります。ファイルを作成後、アプリケーションがそのルートファイルを認識できるように、bootstrap/app.php の withRouting メソッド内で明示的に読み込ませてください。

<?php

use Illuminate\Foundation\Application;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php', // <<< ここを追記
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    );
        

Q. POSTリクエストでデータがコントローラーに届きません/うまく動作しません。

A. データの送信に失敗する場合、クライアント側（Postman、curl、フロントエンドコードなど）でリクエストヘッダーが正しく設定されていない可能性が非常に高いです。特にContent-Type: application/jsonが不足していると、Laravelはリクエストボディを認識できません。

$ curl -X POST http://localhost:8000/api/articles \
-H "Content-Type: application/json" \
-d '{"title":"テスト","body":"本文"}'

別の原因: PUT/PATCHリクエストでデータが届かない場合、HTMLフォームからの送信だとメソッドが正しく認識されないため、APIクライアントの使用を強く推奨します。

Q. データベースにデータが保存されず、エラー（マスアサインメントエラー）になります。

A. これはセキュリティ上の問題を防ぐためのLaravelの仕様です。Eloquentモデル（app/Models/Article.phpなど）で、リクエストから一括で値を割り当てても安全なカラム名を、$fillableプロパティに明示的に設定していないことが原因です。

<?php

use Illuminate\Database\Eloquent\Model;

class Article extends Model {
    /
     * 一括割り当て可能な属性（マスアサインメント許可リスト）。
     * @var array
     */
    protected $fillable = ['title', 'body'];
}

また、逆に$guardedプロパティを使って、マスアサインメントを拒否したいカラムを設定する方法もあります。

Q. LaravelのAPIが「404 Not Found」エラーになるのはなぜですか？

A. 404エラーは「そのURLに対応するルートがない」ことを意味します。主な原因は以下の3点です。

1. ルートの読み込み漏れ: routes/api.phpがbootstrap/app.phpに正しく読み込まれていない（上記Q1参照）。
2. URLのパス間違い: /api/ プレフィックスを忘れている、またはリソース名（例: /api/article ではなく /api/articles）が間違っている。
3. HTTPメソッドの間違い: GETリクエストを送るべきところにPOSTを送っているなど、メソッドがルート定義と一致していない。

Q. LaravelでAPI認証はどうすればいいですか？セッション認証と何が違いますか？

A. Webサイトで使われるセッションベースの認証はAPIには適しません。APIでは一般的にトークンベースの認証を使用します。Laravelでは、Laravel Sanctumという軽量なパッケージを使うことで、トークンベースの認証が簡単に実装できます。

手順: まず composer require laravel/sanctum で導入し、ユーザーがログイン時に発行したトークンを、クライアント側がリクエストヘッダー（例: Authorization: Bearer [トークン]）に含めて送信するように設定します。

Q. 開発中のフロントエンドからAPIを叩くと「CORSエラー」が出ます。

A. CORS (Cross-Origin Resource Sharing) エラーは、異なるドメイン（ポート番号を含む）間でリソースを共有しようとしたときに発生する、Webブラウザのセキュリティ制限です。
対処法: Laravelでは、fruitcake/laravel-cors などのパッケージ（または標準で提供されるミドルウェア）を使って、API側でアクセスを許可するオリジン（ドメイン）を指定する必要があります。config/cors.php ファイルで、開発中のフロントエンドのURL（例: http://localhost:3000）を'allowed_origins'に追加してください。

Q. APIにアクセスしても、ブラウザでJSONレスポンスが空になる、またはエラーではないが何も表示されない。

A. コントローラーのメソッド内で、適切なJSONレスポンスを返していない可能性があります。特にEloquentモデルを返しているつもりでも、エラー処理などが挟まるとレスポンスが曖昧になりがちです。
対処法: 常にresponse()−>json()ヘルパー関数を使って、返却するデータとHTTPステータスコード（例: 200 OK, 201 Createdなど）を明示的に指定するようにしましょう。

<?php

use Illuminate\Http\JsonResponse;

// 成功レスポンスを明示的にJSON形式で返す
return response()−>json(['article' => $article], 200);

まとめ

Laravel 12でRESTfulなAPIを構築する流れを通して、環境構築・ルーティング・コントローラー・モデル・テスト・トラブル対応まで一通りの工程を確認しました。初心者がつまずきやすいポイントを丁寧に押さえながら進めることで、Laravelの設計思想やAPI開発の基本が自然と身につきます。

まずは小さなCRUD APIを完成させることを目標にしましょう。たとえば「記事投稿API」や「メモ管理API」など、身近なテーマで構築すると理解が深まります。実際に手を動かしてみることで、ルーティングの意味やコントローラーの役割、モデルとの連携が実感できるはずです。

次のステップとしては、Laravel Sanctumを使った認証機能の追加や、API Resourceを使ったレスポンスの整形、さらにはバージョニングや検索機能の実装などに挑戦してみると良いでしょう。API開発は一歩ずつ積み重ねることで、確実にスキルが伸びていきます。

「動かない」「分からない」と感じたときは、ログを確認したり、curlでリクエストを送ってみたり、FAQを見直すことで解決の糸口が見つかります。焦らず、ひとつずつ理解していくことが大切です。

このガイドが、Laravel API開発の第一歩となり、あなたの学びと成長につながることを願っています。次は、あなた自身のアイデアを形にする番です。応援しています！