Webアプリケーション開発において、異なるシステム間でデータをやり取りするための仕組みとしてREST API（Representational State Transfer Application Programming Interface）が広く利用されています。
この記事では、REST APIの基本的な概念から、Laravelフレームワークを使って簡単なREST APIを構築する具体的な手順までを、サンプルコードを交えながら解説します。
REST APIの基本
REST APIは、Webの標準技術であるHTTPプロトコルを利用して、リソースと呼ばれる情報にアクセスするための設計原則に基づいたAPIです。
クライアント（Webブラウザやモバイルアプリなど）は、HTTPメソッド（GET, POST, PUT, DELETEなど）を使ってサーバーにリクエストを送信し、サーバーはリソースの状態を表現したレスポンス（JSONやXML形式など）を返します。
RESTの原則
RESTfulなAPIを設計する際には、以下の主要な原則に従うことが推奨されます。
- クライアント/サーバー: クライアントとサーバーは独立して進化できる必要があります。クライアントはサーバーの内部実装を知る必要がなく、サーバーもクライアントの実装に依存しません。
- ステートレス: 各クライアントのリクエストは、サーバーがそのリクエストを処理するために必要なすべての情報を含んでいる必要があります。サーバーはクライアントの状態を保持しません。
- キャッシュ可能: レスポンスはクライアントによってキャッシュ可能であることが望ましいです。これにより、サーバーの負荷を軽減し、クライアントのパフォーマンスを向上させることができます。
- 階層化されたシステム: クライアントは直接サーバーと通信しているか、仲介者（プロキシ、ロードバランサーなど）を経由しているかを意識する必要はありません。
- 統一インターフェース: リソースの識別、リソースの操作、自己記述的なメッセージ、ハイパーメディアによるアプリケーションの状態遷移（HATEOAS）といった一貫したインターフェースを提供する必要があります。
- コード・オン・デマンド（オプション）: サーバーは、クライアントが実行可能なコード（JavaScriptアプレットなど）をレスポンスとして送信できます（必須ではなく、使われないことが多い）。
統一インターフェースのHATEOASについても、実際にAPIを作成するときには省略されることが多いです。
LaravelでREST APIを構築する準備
Laravelは、PHPでWebアプリケーションを迅速かつ容易に開発するための強力なフレームワークであり、REST APIの構築も容易に行えます。
Laravelがインストールされ、基本的な設定が完了している前提で解説を進めます。
まだの場合は、Laravelの公式ドキュメントを参照してインストールと初期設定を行ってください。
Laravelでのルーティング定義
REST APIのエンドポイント（URI）と、それに対応する処理を行うコントローラーのアクションを定義します。
routes/api.php ファイルを作成して編集します。
<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ApiController;
Route::get('/users', [ApiController::class, 'index']); // ユーザー一覧を取得
Route::get('/users/{id}', [ApiController::class, 'show']); // 特定のユーザーを取得
Route::post('/users', [ApiController::class, 'store']); // 新しいユーザーを作成
Route::put('/users/{id}', [ApiController::class, 'update']); // 特定のユーザーを更新
Route::delete('/users/{id}', [ApiController::class, 'destroy']); // 特定のユーザーを削除
上記のルーティング定義では、/api/users というリソースに対して、HTTPメソッドごとに異なるコントローラーのアクションを割り当てています。
apiルートの追加
Laravel12では、apiルートがデフォルトでないためbootstrap/app.phpにルートを追加します。
<?php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
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(function (Middleware $middleware) {
//
})
->withExceptions(function (Exceptions $exceptions) {
//
})->create();
使用するモデル
Laravel12にデフォルトで入っているUserモデルを使います。
app/Models/User.phpにファイルが用意されています。
<?php
namespace App\Models;
// use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
class User extends Authenticatable
{
/** @use HasFactory<\Database\Factories\UserFactory> */
use HasFactory, Notifiable;
/**
* The attributes that are mass assignable.
*
* @var list<string>
*/
protected $fillable = [
'name',
'email',
'password',
];
/**
* The attributes that should be hidden for serialization.
*
* @var list<string>
*/
protected $hidden = [
'password',
'remember_token',
];
/**
* Get the attributes that should be cast.
*
* @return array<string, string>
*/
protected function casts(): array
{
return [
'email_verified_at' => 'datetime',
'password' => 'hashed',
];
}
}
コントローラーの実装
ルーティングで定義した各アクションに対応する処理をコントローラーに実装します。
app/Http/Controllers/ApiController.php を作成または編集します。
<?php
namespace App\Http\Controllers;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
class ApiController extends Controller
{
/**
* ユーザー一覧を取得
*/
public function index(): JsonResponse
{
$users = User::all();
return response()->json($users);
}
/**
* 特定のユーザーを取得
* @param int $id
*/
public function show(int $id): JsonResponse
{
$user = User::findOrFail($id);
return response()->json($user);
}
/**
* 新しいユーザーを作成
* @param Request $request
*/
public function store(Request $request): JsonResponse
{
$user = User::create($request->all());
return response()->json($user, 201); // 201 Created
}
/**
* 特定のユーザーを更新
* @param Request $request
* @param int $id
*/
public function update(Request $request, int $id): JsonResponse
{
$user = User::findOrFail($id);
$user->update($request->all());
return response()->json($user);
}
/**
* 特定のユーザーを削除
* @param int $id
*/
public function destroy(int $id): JsonResponse
{
User::findOrFail($id)->delete();
return response()->json(null, 204); // 204 No Content
}
}
上記のコントローラーでは、LaravelのEloquent ORMを使用してデータベースのusersテーブルに対するCRUD操作を実装しています。
各アクションは Illuminate\Http\JsonResponse 型のレスポンスを返します。
レスポンスの作成
Laravelでは、response()ヘルパー関数やJsonResponseクラスを使って、JSON形式のレスポンスを簡単に作成できます。
HTTPステータスコードを適切に設定することも重要です。
response()->json($data, $status): JSONデータとHTTPステータスコードを指定してレスポンスを作成します。response()->json($data): HTTPステータスコードはデフォルトで200 OKになります。
コントローラーのstoreアクションのように、リソースの作成成功時には201 Createdステータスコードを返すのが一般的です。
また、destroyアクションのように、リソースの削除成功時には204 No Contentステータスコードを返すのが一般的です。
リクエストの処理
クライアントから送信されたリクエストデータ（POSTやPUTリクエストのボディなど）は、コントローラーのメソッドの引数として渡される
Requestオブジェクト(Illuminate\Http\Request)を通じてアクセスできます。
$request->all(): すべてのリクエストデータを配列として取得します。$request->input('key'): 特定のキーのリクエストデータを取得します。$request->validate([...]): リクエストデータのバリデーションを行います。
コントローラーのstoreやupdateアクションのように、リクエストデータを受け取り、それに基づいてデータベースの操作を行います。
Laravelを使ったREST APIの実行サンプル
上記のルーティングとコントローラーの実装により、以下のようなREST APIのエンドポイントが利用可能になります。
ユーザー全員を取得
全てのユーザー情報をJSON形式で取得します。
GET /api/users
[
{
"id": 1,
"name": "taro",
"email": "test@example.com",
"email_verified_at": null,
"created_at": "2025-04-20T00:23:24.000000Z",
"updated_at": "2025-04-20T00:23:24.000000Z"
},
{
"id": 2,
"name": "new user",
"email": "new.user@example.com",
"email_verified_at": null,
"created_at": "2025-04-20T00:55:04.000000Z",
"updated_at": "2025-04-20T00:55:04.000000Z"
},
{
"id": 3,
"name": "hanako",
"email": "hanako@example.com",
"email_verified_at": null,
"created_at": "2025-04-20T00:58:59.000000Z",
"updated_at": "2025-04-20T00:58:59.000000Z"
}
]
指定IDのユーザーを取得
指定されたIDのユーザー情報をJSON形式で取得します。
GET /api/users/{id}
{
"id": 1,
"name": "taro",
"email": "test@example.com",
"email_verified_at": null,
"created_at": "2025-04-20T00:23:24.000000Z",
"updated_at": "2025-04-20T00:23:24.000000Z"
}
ユーザーを追加する
リクエストボディで送信されたユーザー情報に基づいて新しいユーザーを作成し、作成されたユーザー情報をJSON形式で返します（ステータスコード 201）。
POST /api/users
リクエストボディ (例):
["name": "New User", "email": "new.user@example.com", "password": "Password123"] // form request
レスポンス (例):
{
"name": "new user",
"email": "new.user@example.com",
"updated_at": "2025-04-20T00:55:04.000000Z",
"created_at": "2025-04-20T00:55:04.000000Z",
"id": 2
}
ユーザーを更新する
指定されたIDのユーザー情報をリクエストボディで送信された情報に基づいて更新し、更新されたユーザー情報をJSON形式で返します。
PUT /api/users/{id}
リクエストボディ (例):
["name": "yasuaki", "email": "yasuaki@example.com", "password": "Password123"] // form request
レスポンス (例):
{
"id": 2,
"name": "yasuaki",
"email": "yasuaki@example.com",
"email_verified_at": null,
"created_at": "2025-04-20T00:55:04.000000Z",
"updated_at": "2025-04-20T01:08:29.000000Z"
}
ユーザーを削除する
指定されたIDのユーザー情報を削除します（ステータスコード 204）。
DELETE /api/users/{id}
レスポンス: (空)
動作を確認する
実際にサンプルに沿って、POSTMANを使って動作していることを確認します。
ユーザー全員を取得する(index)
/api/usersに対して、GETリクエストを送ることで、ユーザー全員を取得できます。
画面下部に追加されているユーザーが全員表示されました。
ユーザーを取得する(show)
/api/users/{id}に対して、GETリクエストでユーザーを追加します。
{id}の箇所は任意のユーザーIDを指定できるので、1番目を指定して取得しました。
画面下部にid=1のユーザーデータが返ってきていることが確認できます。
ユーザーを追加する(store)
/api/usersに対して、POSTリクエストでユーザーを追加します。
キーと値に入っているのが、入力データで画面下部にレスポンスが表示されています。
入力したデータでユーザーが追加されて、追加したユーザー情報が返ってきました。
ユーザーを更新する(update)
/api/users/{id}に対して、PUTリクエストでユーザーを更新します。
{id}に2を指定して、2番目のユーザーのデータを更新しました。
実行してみると、指定したフォームデータで、ユーザー情報が更新されたことが確認できました。
ユーザーを削除する(delete)
/api/users/{id}に対して、DELETEリクエストでユーザーを更新します。
{id}に3を指定して、3番目のユーザーのデータを削除しました。
削除されて204レスポンスが返ってきました。
まとめ
REST APIは、Webアプリケーション開発における重要なデータ連携の仕組みであり、Laravelを使うことも効率的に構築できます。
この記事で解説したルーティング定義、コントローラーの実装、リクエストとレスポンスの処理といった基本的な手順を理解することで、より複雑なREST APIの開発にも対応できるようになります。
コメント