エラー処理 ¶

RESTful API リクエストを処理する際、ユーザーのリクエストにエラーがある場合や、サーバーで予期しない事態が発生した場合は、例外をスローしてユーザーに何か問題が発生したことを通知するだけで済む場合があります。エラーの原因（例えば、要求されたリソースが存在しないなど）を特定できる場合は、適切な HTTP ステータスコードとともに例外をスローすることを検討する必要があります（例えば、yii\web\NotFoundHttpException は 404 ステータスコードを表します）。Yii は、対応する HTTP ステータスコードとテキストとともにレスポンスを送信します。また、Yii は、レスポンスボディに例外のシリアライズされた表現を含めます。例:

HTTP/1.1 404 Not Found
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "name": "Not Found Exception",
    "message": "The requested resource was not found.",
    "code": 0,
    "status": 404
}

次のリストは、Yii REST フレームワークで使用される HTTP ステータスコードをまとめたものです。

• 200: OK。すべてが期待どおりに機能しました。
• 201: POST リクエストに応じてリソースが正常に作成されました。Location ヘッダーには、新しく作成されたリソースを指す URL が含まれています。
• 204: リクエストは正常に処理され、レスポンスには（DELETE リクエストのように）ボディコンテンツが含まれていません。
• 304: リソースが変更されていません。キャッシュされたバージョンを使用できます。
• 400: 不正なリクエスト。これは、リクエストボディに無効な JSON データを提供したり、無効なアクションパラメータを提供したりするなど、ユーザーによるさまざまなアクションが原因である可能性があります。
• 401: 認証に失敗しました。
• 403: 認証されたユーザーは、指定された API エンドポイントにアクセスすることが許可されていません。
• 404: 要求されたリソースが存在しません。
• 405: メソッドが許可されていません。許可されている HTTP メソッドについては、Allow ヘッダーを確認してください。
• 415: サポートされていないメディアタイプ。要求されたコンテンツタイプまたはバージョン番号が無効です。
• 422: データ検証に失敗しました（例えば、POSTリクエストへの応答の場合）。詳細なエラーメッセージについては、レスポンスボディを確認してください。
• 429: リクエストが多すぎます。リクエストはレート制限のために拒否されました。
• 500: 内部サーバーエラー。これは、内部プログラムエラーが原因である可能性があります。

エラーレスポンスのカスタマイズ ¶

デフォルトのエラーレスポンス形式をカスタマイズしたい場合があります。例えば、異なるエラーを示すために異なるHTTPステータスを使用する代わりに、常にHTTPステータスとして200を使用し、レスポンスのJSON構造の一部として実際のHTTPステータスコードを囲みたい場合があります。以下に示すように。

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "success": false,
    "data": {
        "name": "Not Found Exception",
        "message": "The requested resource was not found.",
        "code": 0,
        "status": 404
    }
}

この目標を達成するには、アプリケーション設定のresponseコンポーネントのbeforeSendイベントに応答できます。

return [
    // ...
    'components' => [
        'response' => [
            'class' => 'yii\web\Response',
            'on beforeSend' => function ($event) {
                $response = $event->sender;
                if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
                    $response->data = [
                        'success' => $response->isSuccessful,
                        'data' => $response->data,
                    ];
                    $response->statusCode = 200;
                }
            },
        ],
    ],
];

上記のコードは、suppress_response_codeがGETパラメータとして渡された場合に説明したように、レスポンス（成功したレスポンスと失敗したレスポンスの両方）を再フォーマットします。