Laravel & Lumen RESTFul API 拡張パッケージ: Dingo API (3) -- Response (レスポンス)

API の主な機能はリクエストを取得し、クライアントにレスポンスを返すことです。レスポンスの形式は JSON など多岐にわたり、レスポンスの返し方もクライアントによって異なります。現在構築中の API の複雑さと将来の考慮事項。

応答を返す最も簡単な方法は、配列またはオブジェクトをコントローラーから直接返すことです。ただし、すべての応答オブジェクトが正しくフォーマットされていることが保証されているわけではないため、それらが ArrayObject または IlluminateSupportContractsArrayableInterface インターフェイスを実装していることを確認する必要があります。 :

class UserController{    public function index()    {        return User::all();    }}

この場合、User クラスは IlluminateDatabaseEloquentModel を継承します。つまり、返されるデータは配列としてフォーマットでき、もちろん単一のユーザーも返すことができます:

class UserController{    public function show($id)    {        return User::findOrFail($id);    }}

Dingo API は、応答を自動的に JSON 形式にフォーマットし、Content-Type ヘッダーを application/json に設定します。

1. レスポンス ビルダー

レスポンス ビルダーは、よりカスタマイズされたレスポンスを簡単に作成できるように、スムーズなインターフェイスを提供します。レスポンス ビルダーは、トランスフォーマーと一緒に使用されることがよくあります。

レスポンス ビルダー コントローラーを使用するには、DingoApiRoutingHelperstrait を使用する必要があります。この特性をすべてのコントローラーで利用できるようにするには、API 基本クラス コントローラー コントローラーに配置します。

use Dingo\Api\Routing\Helpers;use Illuminate\Routing\Controller;class BaseController extends Controller{    use Helpers;}

このコントローラーを継承するコントローラーを定義できるようになりました。このコントローラーでは、$response プロパティを介して応答ビルダーにアクセスできます。

配列応答

class UserController extends BaseController{    public function show($id)    {        $user = User::findOrFail($id);        return $this->response->array($user->toArray());    }}

単一アイテム応答

class UserController extends BaseController{    public function show($id)    {        $user = User::findOrFail($id);        return $this->response->item($user, new UserTransformer);    }}

コレクション応答

class UserController extends BaseController{    public function index()    {        $users = User::all();        return $this->response->collection($users, new UserTransformer);    }}

ページ分割された応答

class UserController extends BaseController{    public function index()    {        $users = User::paginate(25);        return $this->response->paginator($users, new UserTransformer);    }}

コンテンツなし応答

return $this->response->noContent();

応答の作成

return $this->response->created();

リソースの作成時に最初のパラメータとして位置情報を渡すこともできます:

return $this->response->created($location);

エラー応答

さまざまな組み込みエラーがエラー応答を生成します:

// A generic error with custom message and status code.return $this->response->error('This is an error.', 404);// A not found error with an optional message as the first parameter.return $this->response->errorNotFound();// A bad request error with an optional message as the first parameter.return $this->response->errorBadRequest();// A forbidden error with an optional message as the first parameter.return $this->response->errorForbidden();// An internal error with an optional message as the first parameter.return $this->response->errorInternal();// An unauthorized error with an optional message as the first parameter.return $this->response->errorUnauthorized();

追加の応答ヘッダーを追加します

上記の方法を使用した後、応答を追加して応答をカスタマイズすることもできますheaders:

return $this->response->item($user, new UserTransformer)->withHeader('X-Foo', 'Bar');

メタデータの追加

一部の変換レイヤーではメタデータを使用する場合があります。これは、リソースに関連付けられた追加データを提供する必要がある場合に便利です。

return $this->response->item($user, new UserTransformer)->addMeta('foo', 'bar');

メタデータ配列を設定して、複数のメソッド チェーンの呼び出しを置き換えることもできます。

return $this->response->item($user, new UserTransformer)->setMeta($meta);

応答ステータス コードを設定します

return $this->response->item($user, new UserTransformer)->setStatusCode(200);

2. カスタマイズされた応答形式

インストール設定で、Dingo API はデフォルトで自動的に JSON 形式を使用し、対応するコンテンツを設定します。タイプヘッド。 JSON に加えて、JSONP 形式もあります。形式を変更すると、応答がコールバックにカプセル化されます。形式を登録および変更するには、構成ファイル (Laravel) または起動ファイル (Lumen) のデフォルトの JSON 形式を JSONP:

'formats' => [    'json' => 'Dingo\Api\Http\Response\Format\Jsonp']

または:

Dingo\Api\Http\Response::addFormatter('json', new Dingo\Api\Http\Response\Format\Jsonp);

に置き換えるだけです。デフォルトでは、コールバック パラメータのデフォルトのクエリ文字列は callback です。これは、コンストラクタの最初のパラメータを変更することで設定できます。クエリ文字列にパラメータが含まれていない場合は、JSON 応答が返されます。

必要な応答形式を登録して使用することもできます。カスタム形式オブジェクトは DingoApiHttpResponseFormatFormat クラスから継承する必要があり、formatEloquentModel、formatEloquentCollection、formatArray、getContentType のメソッドも実装する必要があります。

3. モーフィングとモーフィング イベント

Dingo API が応答を送信する前に、応答は変換 (モーフ) されます。このプロセスには、すべてのトランスフォーマー (Transformer) の実行が含まれます。そして、設定された応答形式で応答を送信します。応答の変換方法を制御する必要がある場合は、ResponseWasMorphed および ResponseIsMorphing イベントを使用できます。

app/Listeners にイベントのリスナーを作成します:

use Dingo\Api\Event\ResponseWasMorphed;class AddPaginationLinksToResponse{    public function handle(ResponseWasMorphed $event)    {        if (isset($event->content['meta']['pagination'])) {            $links = $event->content['meta']['pagination']['links'];            $event->response->headers->set(                'link',                sprintf('<%s>; rel="next", <%s>; rel="prev"', $links['links']['next'], $links['links']['previous'])            );        }    }}

次に、イベントとそれに対応するリスナーを EventServiceProvider に登録してイベントをリッスンします:

protected $listen = [    'Dingo\Api\Event\ResponseWasMorphed' => [        'App\Listeners\AddPaginationLinksToResponse'    ]];

ページ分割されたリンクを含むすべての応答にも、これらのリンクがリンク ヘッダーに追加されるようになります。

注: この機能は現在まだ開発段階にあり、運用環境での使用は推奨されません。