LaravelでAPI用のコントローラを作成する方法（APIリソース）を初心者向けに解説

LaravelでAPI用のコントローラを作成する方法（APIリソース）

先生と生徒の会話形式で理解しよう

生徒

「LaravelでAPIを作るとき、普通のコントローラと何が違うんですか？」

先生

「API用のコントローラは、主にデータをJSON形式で返すのが特徴です。通常のWebページを返すコントローラとは少し違います。」

生徒

「API用コントローラはどうやって作ればいいですか？」

先生

「LaravelにはAPIリソースという便利な仕組みがあるので、それを使うと簡単に作れますよ。順番に説明しますね。」

1. APIコントローラとは？

APIコントローラは、Webアプリやスマホアプリなどがサーバーとデータをやり取りするときに使う「データ専用の窓口」のような存在です。通常のコントローラがHTMLの画面を返すのに対し、APIコントローラは画面ではなく、アプリが読み取れるJSON形式のデータを返します。画面表示が必要ない分、シンプルで機械が扱いやすい形で情報を届ける役割を持っています。

JSON（ジェイソン）は、{} や [] を使ってデータをわかりやすく整理する形式で、ほとんどのプログラミング言語で簡単に読み書きできます。例えば、APIが返すデータがどのような形か、簡単な例を見るとイメージしやすくなります。


{
    "id": 1,
    "name": "サンプル商品",
    "price": 1200
}

APIコントローラは、このようなデータを返すことで、アプリ側が内容を受け取り、画面に表示したり内部処理に使ったりできるようになります。初心者の方は「HTMLではなく、データそのものを返すコントローラ」と理解するとスムーズに学べます。

2. LaravelでAPIコントローラを作るメリット

LaravelでAPIコントローラを使う一番のメリットは、データのやり取りに特化した仕組みを簡単に扱える点です。APIでは画面を返す必要がなく、必要なのは「正確で扱いやすいデータ」です。そのため、Laravelが用意しているAPI向け機能を使うことで、余計な処理を書かずにスマートなAPIが作れます。

特にRESTful（レストフル）と呼ばれる設計に沿ったAPIを作りやすく、例えば「一覧取得」「新規登録」「更新」「削除」といった基本操作も自然な形で実装できます。名前の付け方やURLの形も決まりがあるため、開発チーム内で統一しやすく、後から見ても理解しやすいコードになります。

また、APIリソースを利用すると、返すJSONデータを整える作業がとても簡単になります。不要な項目を隠したり、表示名をわかりやすく変更したりできるため、APIの利用者にも親切な作りにできます。次のようなシンプルなJSONを返すコード例を見れば、イメージがつかみやすいでしょう。


// 簡単なAPIレスポンス例
return response()->json([
    'message' => 'APIが正しく動作しています！',
    'status' => 'success'
]);

このように、LaravelのAPIコントローラは「分かりやすい」「書きやすい」「管理しやすい」という三拍子がそろっており、初心者でも扱いやすいのが大きな魅力です。

3. APIリソースコントローラの作成方法

ここからは、実際にLaravelでAPI用のコントローラを作成してみましょう。といっても、難しい作業はほとんどありません。Laravelには artisan（アーティザン）コマンド という便利なツールが用意されており、コマンドを1行打つだけで必要なファイルを自動生成してくれます。プログラミング未経験の方でも、コマンドの形だけ覚えてしまえば迷わず進められます。

ターミナル（またはコマンドプロンプト）で、Laravelプロジェクトのフォルダに移動した状態で次のコマンドを実行します。


php artisan make:controller ProductController --api

このコマンドにはいくつか意味があります。

make:controller … 「コントローラファイルを作ってください」という指示
ProductController … 作りたいコントローラの名前（ここでは商品を扱う例）
--api … API専用のコントローラとして作成するオプション

コマンドが成功すると、Laravelが自動的にコントローラファイルを作成し、app/Http/Controllers/ProductController.php が生成されます。自分でフォルダを作ったり、ファイル名を悩んだりする必要はありません。

この ProductController には、APIでよく使う index（一覧取得）、store（新規作成）、show（詳細取得）、update（更新）、destroy（削除）といったメソッドの「受け皿」があらかじめ用意されています。中身はまだ空に近い状態ですが、「どの操作をどこに書けばよいか」の枠が最初からそろっているので、あとから処理を追加していくイメージがつかみやすくなります。

まずは、このコマンドでAPIリソースコントローラの土台を作ることが、LaravelでAPI開発を進めるための最初の一歩です。

4. APIリソースコントローラの中身を見てみよう

前のステップでAPI用のコントローラを作成したら、次は「中身がどうなっているか」を確認してみましょう。難しいことをしているわけではなく、「どのリクエストが来たら、どのメソッドで処理するか」をあらかじめ用意してくれているイメージです。まずは全体像をざっと眺めて、どんな役割のメソッドが並んでいるのかを知るところから始めてみましょう。


namespace App\Http\Controllers;

use App\Models\Product;
use Illuminate\Http\Request;

class ProductController extends Controller
{
    // 商品一覧を取得する処理（GET /api/products）
    public function index()
    {
        $products = Product::all();
        return response()->json($products);
    }

    // 商品を新しく登録する処理（POST /api/products）
    public function store(Request $request)
    {
        $product = Product::create($request->all());
        return response()->json($product, 201);
    }

    // 特定の商品1件を取得する処理（GET /api/products/{id}）
    public function show($id)
    {
        $product = Product::findOrFail($id);
        return response()->json($product);
    }

    // 既存の商品情報を更新する処理（PUT /api/products/{id}）
    public function update(Request $request, $id)
    {
        $product = Product::findOrFail($id);
        $product->update($request->all());
        return response()->json($product);
    }

    // 商品を削除する処理（DELETE /api/products/{id}）
    public function destroy($id)
    {
        Product::destroy($id);
        return response()->json(null, 204);
    }
}

それぞれのメソッドは、APIとしてよく使われる操作に対応しています。例えば index は「一覧を返す」、show は「1件だけ詳しく返す」といった具合です。メソッド名そのものが役割を表しているので、慣れてくるとコードを見ただけでどんなAPIかイメージしやすくなります。

ここで登場する response()->json() は、「渡されたデータをJSON形式にして返す」ためのLaravelの機能です。例えば、次のようなシンプルなメソッドを書けば、APIが正しく動いているか簡単に確認できます。


public function index()
{
    return response()->json([
        'message' => 'APIコントローラからのテストレスポンスです',
        'status'  => 'ok'
    ]);
}

このように「メソッドの役割」と「JSONでデータを返す流れ」を意識しながら中身を読んでいくと、APIリソースコントローラが何をしているのかがぐっと理解しやすくなります。最初は全文を覚えようとせず、「一覧用」「詳細用」「登録用」など、ざっくり役割だけつかんでおくと良いでしょう。

5. API用ルーティングの設定

API用のルートは、通常 routes/api.php に書きます。Route::apiResource を使うと、APIリソースコントローラのルートを簡単にまとめて登録できます。


use App\Http\Controllers\ProductController;

Route::apiResource('products', ProductController::class);

これで、GET /api/products で一覧取得、POST /api/products で新規作成などのAPIが使えるようになります。

6. APIレスポンスの見た目を整える方法

APIリソースをさらに便利に使うために、リソースクラスを作って返すデータを整形できます。これは「必要な情報だけ返す」や「表示名をわかりやすくする」などに役立ちます。

リソースクラスは、以下のコマンドで作成します。


php artisan make:resource ProductResource

作られた ProductResource は次のように使います。


use App\Http\Resources\ProductResource;

public function show($id)
{
    $product = Product::findOrFail($id);
    return new ProductResource($product);
}

このようにすることで、返すJSONの内容を自由にコントロールでき、API利用者にわかりやすく伝えられます。

まとめ

LaravelでAPI用コントローラとAPIリソースを作成する流れを振り返ると、API開発に必要な基本的な概念と実装のポイントが自然と整理されていきます。通常のWebページを返すコントローラとは違い、APIコントローラは主にJSON形式のデータを返すため、よりデータ中心の設計が求められます。今回の記事で扱ったAPIコントローラの作成方法、RESTfulなメソッド構成、APIルートの定義、そして表示データを整えるリソースクラスなどは、LaravelでAPI開発を行う上で欠かせない基礎になります。 APIコントローラを作成する際に使うphp artisan make:controller --apiは、必要なメソッドだけが自動的に生成されるため、初心者でも迷わずに実装に進むことができます。index、store、show、update、destroyのようなRESTの流れに沿ったメソッドが揃っているため、APIの役割を理解しやすく、自然とRESTfulな設計に慣れていける点も大きな特徴です。また、APIリソースを使うことで返却するJSONデータの構造を柔軟にカスタマイズできる点は、実務でも非常に役立ちます。特に、数が多いAPI全体で統一されたレスポンス構造を必要とする場合や、外部システムとの連携に応じてデータを加工する場合、APIリソースは強力な武器になります。データをどのように整形するかをコントローラではなくリソースクラスへ分離できるため、処理の分担が明確になり、コードの見通しも良くなります。さらに、Route::apiResourceを使ったAPIルーティングの自動生成は、Laravelが持つ大きな利点の一つです。複数のルートを一行でまとめて定義できるため、ルーティングの管理が非常に楽になり、規模が大きくなるほどその便利さが際立ちます。APIのエンドポイント管理はミスが起こりやすい部分でもあるため、Laravelが提供する自動生成の仕組みを活用すると、保守性が高く安全なAPI開発が可能になります。また、実際のAPI開発では、バリデーション、例外処理、エラーレスポンスの統一なども必要になるため、APIリソースによるレスポンス整形と組み合わせることで、開発効率と品質が大幅に向上します。データの返し方を明確にコントロールできる設計は、フロントエンド開発者や外部システム利用者にとっても理解しやすく、API利用のミスを防ぐ効果もあります。 APIはスマホアプリやSPA、外部連携などさまざまな場面で必要になる機能であり、LaravelのAPIコントローラとAPIリソースを理解しておくことは、今後の開発で大きな力になります。今回学んだ内容をもとに、さらに高度なAPI設計やセキュリティ、認証機能へと発展させていくことで、より実践的なアプリケーションが作れるようになるでしょう。

サンプルプログラム：APIリソースでJSONレスポンスを整形して返す実装例

APIリソースを使った簡単な実装例を以下に示します。


// ProductResource.php
public function toArray($request)
{
    return [
        'id' => $this->id,
        '商品名' => $this->name,
        '価格' => $this->price,
        '登録日' => $this->created_at->format('Y-m-d'),
    ];
}

// コントローラ側
public function show($id)
{
    $product = Product::findOrFail($id);
    return new ProductResource($product);
}

先生と生徒の振り返り会話

生徒

「APIコントローラって普通のコントローラより少し難しいと思っていましたが、実際にはRESTの形に沿っているので意外とわかりやすかったです！」

先生

「そうですね。Laravelが最初から必要なメソッドを用意してくれるので、流れをつかむとすぐに慣れますよ。」

生徒

「APIリソースでJSONの見た目を整えられるのが便利でした！外部システムにデータを渡すときにも役立ちそうです。」

先生

「そのとおりです。レスポンスを統一すると使う側も安心できます。今回の内容はAPI開発の基礎としてとても大事ですよ。」

生徒

「もっと複雑なAPIも作ってみたくなりました。次は認証付きAPIにも挑戦してみたいです！」