APIレスポンス特性

現代のPHP開発の多くは、JavaScriptを多用するシングルページアプリケーションにデータを提供するだけの単純なAPIであろうと、スタンドアロン製品であろうと、APIの構築を必要とします。CodeIgniterは、どのレスポンスタイプにどのHTTPステータスコードを返す必要があるかを覚える必要なしに、一般的なレスポンスタイプをシンプルにするために、任意のコントローラーで使用できるAPIレスポンス特性を提供します。

使用例

次の例は、コントローラー内での一般的な使用パターンを示しています。

<?php

namespace App\Controllers;

use CodeIgniter\API\ResponseTrait;
use CodeIgniter\Controller;

class Users extends Controller
{
    use ResponseTrait;

    public function createUser()
    {
        $model = new UserModel();
        $user  = $model->save($this->request->getPost());

        // Respond with 201 status code
        return $this->respondCreated();
    }
}

この例では、HTTPステータスコード201が、一般的なステータスメッセージ「作成済み」とともに返されます。最も一般的なユースケースに対応するメソッドが存在します。

<?php

// Generic response method
$this->respond($data, 200);

// Generic failure response
$this->fail($errors, 400);

// Item created response
$this->respondCreated($data);

// Item successfully deleted
$this->respondDeleted($data);

// Command executed by no response required
$this->respondNoContent($message);

// Client isn't authorized
$this->failUnauthorized($description);

// Forbidden action
$this->failForbidden($description);

// Resource Not Found
$this->failNotFound($description);

// Data did not validate
$this->failValidationError($description);

// Resource already exists
$this->failResourceExists($description);

// Resource previously deleted
$this->failResourceGone($description);

// Client made too many requests
$this->failTooManyRequests($description);

レスポンスタイプの処理

これらのメソッドのいずれかにデータを渡すと、次の基準に基づいて結果をフォーマットするデータ型が決定されます。

  • データが文字列の場合、クライアントに返すHTMLとして扱われます。

  • データが配列の場合、コントローラーの$this->format値に従ってフォーマットされます。それが空の場合、クライアントが要求したコンテンツタイプでネゴシエーションを試み、**Config/Format.php**内の$supportedResponseFormatsプロパティで他に何も指定されていない場合は、デフォルトでJSONになります。

使用されるフォーマッタを定義するには、**Config/Format.php**を編集します。$supportedResponseFormatsには、アプリケーションがレスポンスを自動的にフォーマットできるMIMEタイプのリストが含まれています。デフォルトでは、システムはXMLとJSONの両方のレスポンスをフォーマットする方法を知っています。

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class Format extends BaseConfig
{
    public $supportedResponseFormats = [
        'application/json',
        'application/xml',
    ];

    // ...
}

これは、返すレスポンスのタイプを決定するためにコンテンツネゴシエーション中に使用される配列です。クライアントが要求したものとサポートしているものとの間に一致が見つからない場合、この配列の最初のフォーマットが返されます。

次に、データの配列をフォーマットするために使用されるクラスを定義する必要があります。これは完全修飾クラス名である必要があり、クラスはCodeIgniter\Format\FormatterInterfaceを実装する必要があります。フォーマッタには、JSONとXMLの両方をサポートするものがすぐに使用できます。

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class Format extends BaseConfig
{
    public $formatters = [
        'application/json' => \CodeIgniter\Format\JSONFormatter::class,
        'application/xml'  => \CodeIgniter\Format\XMLFormatter::class,
    ];

    // ...
}

したがって、リクエストが**Accept**ヘッダーでJSON形式のデータを要求する場合、respond*またはfail*メソッドに渡すデータ配列は、CodeIgniter\Format\JSONFormatterクラスによってフォーマットされます。結果のJSONデータがクライアントに返されます。

クラスリファレンス

setResponseFormat($format)
パラメーター:

  • $format (string) – 返すレスポンスのタイプ。 jsonまたはxmlのいずれかです

これは、レスポンスで配列をフォーマットする際に使用されるフォーマットを定義します。$formatにnull値を指定すると、コンテンツネゴシエーションを通じて自動的に決定されます。

<?php

return $this->setResponseFormat('json')->respond(['error' => false]);
respond($data[, $statusCode = 200[, $message = '']])
パラメーター:

  • $data (mixed) – クライアントに返すデータ。文字列または配列のいずれか。

  • $statusCode (int) – 返すHTTPステータスコード。デフォルトは200

  • $message (string) – 返すカスタムの「理由」メッセージ。

これは、この特性の他のすべてのメソッドがクライアントにレスポンスを返すために使用するメソッドです。

$data要素には、文字列または配列のいずれかを指定できます。デフォルトでは、文字列はHTMLとして返され、配列はコンテンツネゴシエーションで別の形式で返す必要があると判断されない限り、json_encodeを介して実行され、JSONとして返されます。

$message文字列が渡された場合、レスポンスステータスの標準IANA理由コードの代わりにそれが使用されます。ただし、すべてのクライアントがカスタムコードを尊重するわけではなく、ステータスコードに一致するIANA標準を使用します。

注

アクティブなレスポンスインスタンスにステータスコードとボディを設定するため、これは常にスクリプト実行の最後のメソッドである必要があります。

fail($messages[, int $status = 400[, string $code = null[, string $message = '']]])
パラメーター:

  • $messages (mixed) – 発生したエラーメッセージを含む文字列または文字列の配列。

  • $status (int) – 返すHTTPステータスコード。デフォルトは400。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

クライアントが優先する形式での複数部分のレスポンス。

これは、失敗したレスポンスを表すために使用される一般的なメソッドであり、他のすべての「fail」メソッドで使用されます。

$messages要素には、文字列または文字列の配列のいずれかを指定できます。

$statusパラメーターは、返す必要のあるHTTPステータスコードです。

多くのAPIではカスタムエラーコードを使用する方が適切であるため、3番目のパラメーターでカスタムエラーコードを渡すことができます。値がない場合、それは$statusと同じになります。

$message文字列が渡された場合、レスポンスステータスの標準IANA理由コードの代わりにそれが使用されます。ただし、すべてのクライアントがカスタムコードを尊重するわけではなく、ステータスコードに一致するIANA標準を使用します。

レスポンスは、error と messages の2つの要素を持つ配列です。error 要素には、エラーのステータスコードが含まれます。messages 要素には、エラーメッセージの配列が含まれます。以下のような形式になります。

<?php

$response = [
    'status'   => 400,
    'code'     => '321a',
    'messages' => [
        'Error message 1',
        'Error message 2',
    ],
];
respondCreated($data = null[, string $message = ''])
パラメーター:

  • $data (mixed) – クライアントに返すデータ。文字列または配列のいずれか。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

新しいリソースが作成された際に使用する適切なステータスコードを設定します。通常は201です。

<?php

$user = $userModel->insert($data);

return $this->respondCreated($user);
respondDeleted($data = null[, string $message = ''])
パラメーター:

  • $data (mixed) – クライアントに返すデータ。文字列または配列のいずれか。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

API呼び出しの結果として新しいリソースが削除された際に使用する適切なステータスコードを設定します。通常は200です。

<?php

$user = $userModel->delete($id);

return $this->respondDeleted(['id' => $id]);
respondNoContent(string $message = 'No Content')
パラメーター:

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

コマンドがサーバーによって正常に実行されたが、クライアントに送信する意味のある応答がない場合に使用する適切なステータスコードを設定します。通常は204です。

<?php

sleep(1);

return $this->respondNoContent();
failUnauthorized(string $description = 'Unauthorized'[, string $code = null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

ユーザーが認証されていないか、不正な認証情報を持っている場合に使用する適切なステータスコードを設定します。ステータスコードは401です。

<?php

return $this->failUnauthorized('Invalid Auth token');
failForbidden(string $description = 'Forbidden'[, string $code=null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

failUnauthorized()とは異なり、このメソッドは、要求されたAPIエンドポイントが許可されない場合に使用する必要があります。Unauthorizedは、クライアントが異なる認証情報で再試行することを推奨していることを意味します。Forbiddenは、クライアントが再試行しても意味がないことを意味します。ステータスコードは403です。

<?php

return $this->failForbidden('Invalid API endpoint.');
failNotFound(string $description = 'Not Found'[, string $code=null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

要求されたリソースが見つからない場合に使用する適切なステータスコードを設定します。ステータスコードは404です。

<?php

return $this->failNotFound('User 13 cannot be found.');
failValidationErrors($errors[, string $code=null[, string $message = '']])
パラメーター:

  • $errors (mixed) – ユーザーに表示するエラーメッセージまたはメッセージの配列。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

クライアントが送信したデータが検証ルールに合格しなかった場合に使用する適切なステータスコードを設定します。ステータスコードは通常400です。

<?php

return $this->failValidationErrors($validation->getErrors());
failResourceExists(string $description = 'Conflict'[, string $code=null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

クライアントが作成しようとしているリソースがすでに存在する場合に使用する適切なステータスコードを設定します。ステータスコードは通常409です。

<?php

return $this->failResourceExists('A user already exists with that email.');
failResourceGone(string $description = 'Gone'[, string $code=null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

要求されたリソースが以前に削除され、利用できなくなった場合に使用する適切なステータスコードを設定します。ステータスコードは通常410です。

<?php

return $this->failResourceGone('That user has been previously deleted.');
failTooManyRequests(string $description = 'Too Many Requests'[, string $code=null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

クライアントがAPIエンドポイントを過度に呼び出した場合に使用する適切なステータスコードを設定します。これは、何らかのスロットリングまたはレート制限による可能性があります。ステータスコードは通常400です。

<?php

return $this->failTooManyRequests('You must wait 15 seconds before making another request.');
failServerError(string $description = 'Internal Server Error'[, string $code = null[, string $message = '']])
パラメーター:

  • $description (string) – ユーザーに表示するエラーメッセージ。

  • $code (string) – カスタムのAPI固有のエラーコード。

  • $message (string) – 返すカスタムの「理由」メッセージ。

戻り値:

Responseオブジェクトのsend()メソッドの値です。

サーバーエラーが発生した場合に使用する適切なステータスコードを設定します。

<?php

return $this->failServerError('Server error.');