Laravel API Resource を用いたレスポンス整形 前編

Laravel で Eloquent を用いた API レスポンスを整形する API Resource クラスについての紹介をしていきます。

API Resource

API Resourceは Eloquent のデータを整形・加工するためのクラスです。

例えば Message Eloquent があるケースで、メッセージの一覧を取得するAPI は次のように記述します。

class MessageController{

    public function get($id){
        return Message::find($id);
    }

    public function getAll(){
        return Message::all();
    }
}

Eloquent の検索結果をそのまま return してAPIを生成するのは、
コードの記述量も少なく非常に便利ですが、一方で、レスポンスに created_atid などの必要でないフィールドまで含まれるのが不便なケースもあります。

API Resource はこうした問題を解決するために便利な機能を提供してくれます。

API Resource は次のように作成します。

<?php
namespace App\Http\Resource;

use Illuminate\Http\Resources\Json\JsonResource;

class MessageResource extends JsonResource {

    public function toArray($request){
        return [
            "message" => $this->message,
            "message_at" => $this->message_at,
        ];
    }

}

API Resource クラスのルールとして Illuminate\Http\Resources\Json\JsonResource クラスを継承する必要があります。クラス名の規約は特にありませんが、 Http 名前空間内で、Eloquent と紐付けられるような命名ルールを設けておくのが良いでしょう。

toArray の中でEloquent モデルの整形を行うことができ、
個別の Eloquent モデルをAPIレスポンスの中でどの様に表現するかを定義できます。

作成した API Resource クラスは以下のようにして使用します。

class MessageController{

    public function get($id){
        $message = Message::find($id);
        return new MessageResource($message);
    }
}

API Resource クラスをnew してコンストラクタに Eloquent モデルを渡し、その戻り値を API のレスポンスとして返却すればOKです。

また、getall で取得できる、複数の Eloquent のCollectionをラップして使うことも出来ます。

class MessageController{

    public function getAll(){
        return MessageResource::collection(Message::all());
    }
} 

もちろん、レスポンスボディの下層に混ぜることも可能です。

class MessageController{

    public function getAll(){
        $messages = MessageResource::collection(Message::all());
        return [
            "count" => count($messages),
            "messages" => $messages
        ];
    }
} 

API Resource クラスを正しく適用して、API のレスポンスに必要な項目だけを提供することは、REST APIの保守性を大きく向上させます。

単純に Eloquent モデルを return するだけのAPI開発はシンプルで簡単な反面、不要な値を外部に公開したり、公開スべきではない値を公開してセキュリティリスクを高めたりする原因となりますのでAPI Resource クラスを使用したレスポンス項目の整形を習慣づけるほうがよいでしょう。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です