クイックスタート ¶

Yiiは、RESTful WebサービスAPIの実装タスクを簡素化するためのツールセットを提供します。特に、YiiはRESTful APIに関する以下の機能をサポートしています。

• アクティブレコードに対する一般的なAPIのサポートによるクイックプロトタイピング。
• レスポンス形式のネゴシエーション（デフォルトでJSONとXMLをサポート）。
• 選択可能な出力フィールドをサポートしたカスタマイズ可能なオブジェクトシリアライゼーション。
• コレクションデータと検証エラーの適切な整形。
• コレクションのページネーション、フィルタリング、ソート。
• HATEOASのサポート。
• 適切なHTTP動詞チェックによる効率的なルーティング。
• OPTIONSおよびHEAD動詞の組み込みサポート。
• 認証と認可。
• データキャッシュとHTTPキャッシュ。
• レート制限。

以下では、最小限のコーディング作業でRESTful APIのセットを構築する方法を例を挙げて説明します。

RESTful API経由でユーザーデータを公開したいと仮定します。ユーザーデータはuser DBテーブルに保存されており、ユーザーデータにアクセスするためにアクティブレコードクラスapp\models\Userを既に作成しているとします。

コントローラの作成 ¶

まず、次のようにコントローラクラスapp\controllers\UserControllerを作成します。

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}

コントローラクラスはyii\rest\ActiveControllerから拡張され、これは一般的なRESTfulアクションのセットを実装します。modelClassをapp\models\Userとして指定することにより、コントローラはデータの取得と操作に使用できるモデルを認識します。

URLルールの設定 ¶

次に、アプリケーション設定でurlManagerコンポーネントの設定を変更します。

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
    ],
]

上記の構成では、主にuserコントローラのURLルールを追加して、きれいなURLと意味のあるHTTP動詞を使用してユーザーデータにアクセスおよび操作できるようにします。

注意: Yiiは、エンドポイントで使用するためにコントローラ名を自動的に複数形にします（以下の試してみるセクションを参照）。これは、yii\rest\UrlRule::$pluralizeプロパティを使用して設定できます。

JSON入力の有効化 ¶

APIがJSON形式の入力データを受け入れられるようにするには、JSON入力にyii\web\JsonParserを使用するように、request アプリケーションコンポーネントのparsersプロパティを設定します。

'request' => [
    'parsers' => [
        'application/json' => 'yii\web\JsonParser',
    ]
]

情報: 上記の設定はオプションです。上記の設定がない場合、APIはapplication/x-www-form-urlencodedおよびmultipart/form-data入力形式のみを認識します。

試してみる ¶

上記の最小限の作業で、ユーザーデータにアクセスするためのRESTful APIの作成タスクを既に完了しています。作成したAPIには以下が含まれます。

• GET /users: ユーザーをページごとに一覧表示します。
• HEAD /users: ユーザー一覧の概要情報を表示します。
• POST /users: 新しいユーザーを作成します。
• GET /users/123: ユーザー123の詳細を返します。
• HEAD /users/123: ユーザー123の概要情報を表示します。
• PATCH /users/123 および PUT /users/123: ユーザー123を更新します。
• DELETE /users/123: ユーザー123を削除します。
• OPTIONS /users: エンドポイント/usersに関するサポートされている動詞を表示します。
• OPTIONS /users/123: エンドポイント/users/123に関するサポートされている動詞を表示します。

次のように、curlコマンドでAPIにアクセスできます。

$ curl -i -H "Accept:application/json" "https:///users"

HTTP/1.1 200 OK
...
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http:///users?page=1>; rel=self, 
      <http:///users?page=2>; rel=next, 
      <http:///users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

[
    {
        "id": 1,
        ...
    },
    {
        "id": 2,
        ...
    },
    ...
]

許容されるコンテンツタイプをapplication/xmlに変更すると、結果がXML形式で返されることがわかります。

$ curl -i -H "Accept:application/xml" "https:///users"

HTTP/1.1 200 OK
...
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item>
        <id>1</id>
        ...
    </item>
    <item>
        <id>2</id>
        ...
    </item>
    ...
</response>

次のコマンドは、JSON形式のユーザーデータを含むPOSTリクエストを送信することにより、新しいユーザーを作成します。

$ curl -i -H "Accept:application/json" -H "Content-Type:application/json" \
    -XPOST "https:///users" \
    -d '{"username": "example", "email": "user@example.com"}'

HTTP/1.1 201 Created
...
Location: http:///users/1
Content-Length: 99
Content-Type: application/json; charset=UTF-8

{"id":1,"username":"example","email":"user@example.com","created_at":1414674789,"updated_at":1414674789}

ヒント： WebブラウザーでURL https:///usersを入力してAPIにアクセスすることもできます。ただし、特定の要求ヘッダーを送信するには、ブラウザーのプラグインが必要になる場合があります。

ご覧のとおり、レスポンスヘッダーには、合計件数、ページ数などの情報が含まれています。また、他のデータページに移動できるリンクもあります。たとえば、https:///users?page=2は、ユーザーデータの次のページを提供します。

fieldsおよびexpandパラメーターを使用すると、結果に含める必要があるフィールドを指定することもできます。たとえば、URL https:///users?fields=id,emailは、idとemailフィールドのみを返します。

情報： https:///usersの結果には、password_hash、auth_keyなどの機密フィールドが含まれていることに気づいたかもしれません。これらのフィールドをAPIの結果に表示させたくないことは確かです。 リソースセクションで説明されているように、これらのフィールドを結果から削除することができます。

さらに、https:///users?sort=emailやhttps:///users?sort=-emailのようにコレクションをソートすることもできます。 https:///users?filter[id]=10やhttps:///users?filter[email][like]=gmail.comのようにコレクションをフィルタリングすることも、データフィルターを使用して実装できます。詳細については、コレクションのフィルタリングセクションを参照してください。

リスト内のページネーションとソートのカスタマイズ ¶

モデルリストのデフォルトのページネーションおよびソートを変更するには、コントローラーでyii\rest\IndexActionを構成できます。例：

<?php
namespace app\controllers;

use yii\rest\ActiveController;
use yii\helpers\ArrayHelper;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
    
    public function actions()
    {
        return ArrayHelper::merge(parent::actions(), [
            'index' => [
                'pagination' => [
                    'pageSize' => 10,
                ],
                'sort' => [
                    'defaultOrder' => [
                        'created_at' => SORT_DESC,
                    ],
                ],
            ],
        ]);
    }
}

ActiveControllerのアクションを構成する方法の詳細については、ActiveControllerの拡張を参照してください。

まとめ ¶

Yii RESTful APIフレームワークを使用すると、コントローラーアクションの観点からAPIエンドポイントを実装し、コントローラーを使用して、単一タイプのリソースのエンドポイントを実装するアクションを整理します。

リソースは、yii\base\Modelクラスから拡張されたデータモデルとして表されます。データベース（リレーショナルまたはNoSQL）を操作している場合は、ActiveRecordを使用してリソースを表すことをお勧めします。

yii\rest\UrlRuleを使用して、APIエンドポイントへのルーティングを簡略化できます。

必須ではありませんが、保守を容易にするために、Webフロントエンドおよびバックエンドとは異なる、独立したアプリケーションとしてRESTful APIを開発することをお勧めします。