バックエンドのスタンダード：Laravel入門

■第10話：API開発の基礎

（最終更新日：2024.07.21）

「APIを使おう」

API認証は、APIを保護し、正当なユーザーのみがアクセスできるようにするために重要だ。 Laravelでは、SanctumやPassportを使用して簡単にトークンベースの認証を実装できる。 それぞれの方法には異なる利点があり、APIの規模や要件に応じて適切な方法を選択することが重要になる。

１.RESTful APIの設計

RESTful API（Representational State Transfer）とは、HTTPプロトコルをベースにしたシンプルなアーキテクチャだ。 RESTful APIの設計では、以下のポイントに注意する。

１.１ リソースの定義
RESTful APIでは、すべてがリソースとして扱われる。 リソースは、名詞で表現されるエンティティであり、例えば「ユーザー」「投稿」「コメント」などが該当する。 各リソースには一意のURLが割り当てられる。以下は一例である。

1. GET /users：ユーザー一覧を取得
2. GET /users/{id}：特定のユーザーを取得
3. POST /users：新しいユーザーを作成
4. PUT /users/{id}：特定のユーザーを更新
5. DELETE /users/{id}：特定のユーザーを削除

１.２ HTTPメソッドの使用
RESTful APIでは、HTTPメソッドを利用してリソースに対する操作を定義する。 主なHTTPメソッドとその役割は次の通りになる。 GETはリソースの取得（読み取り操作）、POSTは新しいリソースの作成、PUTは既存リソースの全体更新、 PATCHは既存リソースの部分更新、DELETEは既存リソースの削除になる。

１.３ URIの設計
URI（Uniform Resource Identifier）は、リソースの場所を示す識別子だ。 URIは階層構造を持ち、リソースを論理的に整理するために使う。 各レベルはスラッシュで区切る。

1. GET /users/{userId}/posts：特定のユーザーの投稿一覧を取得
2. POST /users/{userId}/posts：特定のユーザーに新しい投稿を追加
3. GET /users/{userId}/posts/{postId}：特定のユーザーの特定の投稿を取得

１.４ ステータスコードの利用
HTTPステータスコードを適切に使用して、クライアントに操作の結果を通知する。 主要なステータスコードは以下の通りになる。

1. 200 OK：リクエストが成功し、レスポンスが含まれている
2. 201 Created：リソースが正常に作成された
3. 204 No Content：リクエストは成功したが、レスポンスボディは存在しない
4. 400 Bad Request：リクエストが不正である
5. 401 Unauthorized：認証が必要である
6. 404 Not Found：リソースが見つからない
7. 500 Internal Server Error：サーバー側でエラーが発生した

１.５ エラーハンドリング
エラーハンドリングは、API設計の重要な要素だ。 クライアントが適切にエラーを処理できるように、エラーメッセージを一貫した形式で提供する。

１.６ 認証と認可
セキュリティを確保するために、適切な認証と認可を導入する。 APIキー、OAuth、JWTなどの方法がある。

１.７ ドキュメントの整備
APIのドキュメントを整備することで、開発者がAPIを理解しやすくなる。 SwaggerやOpenAPIなどのツールを利用して、自動生成やインタラクティブなドキュメントを提供することが推奨される。

以上がRESTful APIの基本設計に関する要点だ。 APIの設計は、利用者の視点を重視し、シンプルで直感的にすることが重要になる。

２.ルートとコントローラの設定

Laravelを使ったAPI開発の基礎として、ルートとコントローラの設定は重要なステップだ。 以下では、ルートとコントローラの設定方法について詳しく説明する。

２.１ ルートの設定
ルートは、特定のURLに対するリクエストをどのコントローラのメソッドで処理するかを決定する。 APIルートは通常、routes/api.phpファイルに定義する。下記に、そのファイルの例を示す。 このファイルでは、ユーザー一覧を取得する（GET /users）、特定のユーザーを取得する（GET /users/{id}）、 新しいユーザーを作成する（POST /users）、特定のユーザーを更新する（PUT /users/{id}）、 特定のユーザーを削除する（DELETE /users/{id}）を定義している。

２.２ コントローラの設定
コントローラは、ルートで定義されたURLに対するリクエストを処理するためのクラスだ。 Laravelでは「php artisan make:controller」コマンドを使って簡単にコントローラを作成できる。 下記では「php artisan make:controller UserController」でUserController.php」ファイルを作成し、 リクエストを処理するためのメソッドを追加している。

このコントローラには、ユーザー一覧を取得してJSON形式で返す（index()）、特定のIDのユーザーを取得してJSON形式で返す（show($id)）、 新しいユーザーを作成する（store(Request $request)）、特定のIDのユーザー情報を更新する（update(Request $request, $id)）、 特定のIDのユーザーを削除する（destroy($id)）を追加している。

２.３ バリデーション
コントローラメソッド内で、リクエストデータのバリデーションを行う。 $request->validate()メソッドを使って、必要なバリデーションルールを定義する。

２.４ レスポンスの返却
コントローラメソッドでは、適切なHTTPステータスコードとともにJSONレスポンスを返すことが一般的だ。 response()->json()メソッドを使用する。 例えば、2.2のUserController.phpのコードで記述した各return部分の記述がそれにあたる。

これで、Laravelのルートとコントローラの基本的な設定方法がわかったと思う。 APIの開発においては、適切なルート設定とコントローラの実装が重要になる。

３.リソースとAPIリソース

Laravelでは、API開発の際にリソース（Resource）とAPIリソース（API Resource）を使用してデータを整形し、 クライアントに返すための便利な機能を提供している。これにより、JSONレスポンスのカスタマイズが容易になり、APIの開発効率が向上する。

３.１ リソースとは
リソースは、データベースから取得したモデルやコレクションをJSON形式に変換するためのクラスだ。 これにより、データの整形やフィルタリングが簡単に行える。 リソースを作成するには、まず「php artisan make:resource UserResource」でUserResourceクラスを作成する。 そして、下記のように設定することで、id、name、email、created_at、updated_atの値をJSONで取得することができる。 このクラスは、Userモデルのインスタンスを受け取り、toArrayメソッドでJSON形式に変換する。

３.２ APIリソースとは
APIリソースは、リソースクラスを拡張して、データのコレクションを整形するためのクラスだ。 通常、複数のリソースを一度に返す際に使用する。UserCollectionクラスは3.1と同じ方法で作成する。

data キーの下に複数のユーザーリソースが含まれ、そのメタ情報として、meta キーの下に total_users キーが含む。 このようにして、複数のリソースを返すための構造が形成されている。 例えば、UserCollection を返すAPIエンドポイントを実装すると、次のようなJSONレスポンスが生成される。

３.３ リソースとAPIリソースの使用
リソースやAPIリソースをコントローラで使用することで、整形されたJSONレスポンスを簡単に返すことができる。 このコントローラでは、先ほど作成したUserResourceとUserCollectionを使用して、 単一のユーザーやユーザーのコレクションを整形して、JSONレスポンスを返している。

３.４ APIリソースの追加機能
APIリソースには、データに対する追加のメタ情報を含めることもできる。 たとえば、ページネーション情報やリンクを追加することができる。

この記述することで、ページネーション情報が含まれたJSONレスポンスが返される。 具体的には以下のようなページネーション情報がJSONに記される。

リソースとAPIリソースを使用することで、LaravelのAPI開発において、データの整形やフィルタリングが容易になる。 これにより、クライアントに対して一貫性のあるレスポンスを提供することができ、APIの開発効率が上がる。

４.API認証

API開発において、認証は非常に重要な要素だ。 認証を適切に設定することで、APIを利用するユーザーを特定し、保護されたリソースへのアクセスを制御できる。 Laravelでは、API認証のための様々な方法が提供されている。 ここでは、最も一般的な方法として、トークンベースの認証について説明する。

４.１ トークンベースの認証
トークンベースの認証は、APIクライアントがサーバーから発行されたトークンを使用して認証を行う方法だ。 Laravelでは、主に以下の方法でトークンベースの認証を実現できる。

４.１.１Laravel Sanctum
Laravel Sanctumは、シンプルなAPIトークン認証を提供するパッケージだ。 SPA（Single Page Application）やモバイルアプリケーション、シンプルなトークンベースのAPI認証に適している。

Sanctumのインストールと設定
Sanctumはcomposerを用いて簡単にインストールできる。「composer require laravel/sanctum」とコマンドを打つだけだ。 それから、Sanctumのサービスプロバイダを、configのapp.phpで登録する。

その後、マイグレーションを実行する。 これらのコマンドを入力すると、Laravel Sanctumのための必要なデータベーステーブルが作成される。

最初のコマンドでは、Laravel Sanctumの構成ファイルをプロジェクトにコピーする。 このファイルは通常、config/sanctum.php に配置される。 この構成ファイルには、Sanctumの設定をカスタマイズするためのオプションが含まれている。 そして、次のコマンドでデータベースマイグレーションを実行している。 personal_access_tokensテーブルが作成される。 このテーブルには、トークンやトークン名、作成、更新日時などが保存される。

次にSanctumのミドルウェアを設定する。 EnsureFrontendRequestsAreStateful::classでは、フロントエンドのリクエストが状態を保持する。 Sanctumを使用する際に、フロントエンドとバックエンドが同じドメインで動作している場合に使用する。 このミドルウェアは、クッキーを使用してユーザーの認証情報を管理し、クッキーの状態を維持するために必要だ。

throttle:apiでは、APIリクエストのレート制限を適用する。デフォルトでは、1分間に60回のリクエストが許可される。 この制限を超えるリクエストは、429 Too Many Requests のHTTPステータスコードと共に拒否される。 このミドルウェアは、サーバーの負荷を軽減し、サービスの品質を保つために使用される。

SubstituteBindings::classでは、ルートモデルのバインディングと解決を行う。 例えば、ルートに {user} が含まれている場合、このミドルウェアはその部分を対応するユーザーモデルに置き換える。 この機能により、ルートパラメータを自動的にモデルインスタンスに解決することができる。

HasApiTokensトレイトをUserモデルに追加する。 これにより、ユーザーがAPIトークンを管理できるようになる。 ユーザーはAPIトークンを発行し、そのトークンを使ってAPIリクエストを認証できる。 また、Notifiableでは通知機能を提供する。ユーザーはメール、データベース、SMSなどを通じて通知を受け取れる。

APIトークンの発行する。 APIエンドポイント /login を作成して、ユーザーのログイン認証とAPIトークンの生成を行う。 具体的には、use Illuminate\Http\RequestでHTTPリクエストにアクセスするための Request クラスをインポートしている。 use App\Models\Userでは、ユーザーモデル User をインポートしています。これにより、ユーザーに関するデータベース操作が可能になる。 Route::post('/login', function (Request $request) { ... })では、HTTP POSTリクエストを /login エンドポイントに対して定義している。 このエンドポイントはユーザーのログイン処理を担当する。 $user = User::where('email', $request->email)->first()では、リクエストのemailフィールドに基づき、データベースからユーザーを検索し、最初の結果を取得する。 if (! $user || ! Hash::check($request->password, $user->password)) { ... }では、ユーザーやパスワードが一致しない場合にエラーを返す。 $token = $user->createToken('api-token')->plainTextTokenでは、ユーザーのために新しいAPIトークンを生成し、平文トークンを取得する。 createTokenメソッドは、指定されたトークン名を持つ新しいパーソナルアクセストークンを生成する。 最後に、return response()->json(['token' => $token])で生成されたAPIトークンをJSON形式でクライアントに返す。

クライアントは、認証ヘッダにAPIトークンを含めてリクエストを送信する。

API側では、auth:sanctumミドルウェアを使用して認証を行う。

以上がLaravel Sanctumで認証を行う方法になる。

４.１.２ Laravel Passport
Laravel Passportは、OAuth2サーバーを簡単に構築できるパッケージだ。 大規模なAPIやサードパーティのアプリケーションとの連携に適している。 パッケージのインストールは「composer require laravel/passport」で行う。 それから、Passportのサービスプロバイダを登録を行う。

下記コマンドで、マイグレーションとLaravel Passportのインストールを行う。

HasApiTokensトレイトをUserモデルに追加する。 APIトークンを管理できるようになるのはSamctumと同じだが、ここではOAuth2認証を扱うための機能を持つようになる。 OAuth2認証のために必要なメソッドやプロパティを追加している。

Passportのルートを設定する。 このコードは、LaravelアプリケーションでOAuth2認証を設定するために必要な初期化処理を行っている。 具体的には、use Laravel\Passport\Passportでは、Laravel Passportパッケージから Passport クラスをインポートしている。 Passportクラスは、LaravelアプリケーションにOAuth2認証を提供するための主要なクラスだ。 $this->registerPolicies()は、アプリケーションの認可ポリシーを登録する。 認可ポリシーは、特定のアクションを実行するユーザーの権限をチェックするためのものだ。 このメソッドは、通常、AuthServiceProviderクラスの親クラスで定義される。 Passport::routes()でLaravel Passportのルートを登録します。このメソッドを呼び出すことで、 OAuth2認証に必要な一連のルート（トークン発行、クライアント管理、認証スコープの定義）が自動的に登録される。

API認証の設定をする。認証ドライバーをpassportに設定し、 ユーザープロバイダーをusersとしている。 users プロバイダは通常、config/auth.php の providers 配列で定義されている。

最後にクライアントトークンを発行し、クライアントIDとシークレットを使用してアクセストークンを取得する。

クライアントはアクセストークンを取得し、認証ヘッダに含めてリクエストを送信する。 送信の方法は、Sanctumで示したクライアントのリクエスト送信と全く同じコマンドで行うことができる。

４.２ その他の認証方法
API認証には他にも様々な方法がある。 Laravelの認証機能を拡張したり、カスタムミドルウェアを作成して独自の認証ロジックを実装することも可能だ。

API認証は、APIを保護し、正当なユーザーのみがアクセスできるようにするために重要だ。 Laravelでは、SanctumやPassportを使用して簡単にトークンベースの認証を実装できる。 それぞれの方法には異なる利点があり、APIの規模や要件に応じて適切な方法を選択することが重要になる。

５.まとめ

第10回では、Laravelを使ったAPI開発の基礎について学んだ。 RESTful APIの設計原則を理解し、ルートとコントローラの設定方法を解説した。 リソースとAPIリソースの活用により、データの表現を簡潔に行う方法を紹介した。 また、API認証についても詳しく説明し、安全なAPI開発のためのベストプラクティスを学んだ。 これにより、効率的かつセキュアなAPI開発の基本スキルを習得できるようになる。

▼参考図書、サイト

 「改定2版 速習Laravel」　山田祥寛　WINGSプロジェクト
 「1週間で基礎から学ぶLaravel入門」　Minatomi