ルーティング ¶

リソースとコントローラークラスの準備が整ったら、`https:///index.php?r=user/create`のようなURLを使用してリソースにアクセスできます。これは、通常のWebアプリケーションで行うことができる操作と同様です。

実際には、通常は分かりやすいURLを有効にして、HTTP動詞を利用したいと考えています。たとえば、`POST /users`リクエストは`user/create`アクションへのアクセスを意味します。これは、次のようにアプリケーション設定で`urlManager` アプリケーションコンポーネント を構成することで簡単に実現できます。

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

WebアプリケーションのURL管理と比較して、上記の主な新しい点は、RESTful APIリクエストのルーティングにyii\rest\UrlRule を使用していることです。この特別なURLルールクラスは、指定されたコントローラーのルーティングとURL作成をサポートするために、一連の子URLルールを作成します。たとえば、上記のコードは次のルールとほぼ同等です。

[
    'PUT,PATCH users/<id>' => 'user/update',
    'DELETE users/<id>' => 'user/delete',
    'GET,HEAD users/<id>' => 'user/view',
    'POST users' => 'user/create',
    'GET,HEAD users' => 'user/index',
    'users/<id>' => 'user/options',
    'users' => 'user/options',
]

そして、次の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に関するサポートされている動詞を表示します。

onlyオプションとexceptオプションを設定して、サポートするアクション、または無効にするアクションを明示的にリストすることができます。例:

[
    'class' => 'yii\rest\UrlRule',
    'controller' => 'user',
    'except' => ['delete', 'create', 'update'],
],

また、既存のパターンを再定義したり、このルールでサポートされる新しいパターンを追加するために、patternsまたはextraPatternsを設定することもできます。たとえば、エンドポイントGET /users/searchで新しいアクションsearchをサポートするには、extraPatternsオプションを次のように設定します。

[
    'class' => 'yii\rest\UrlRule',
    'controller' => 'user',
    'extraPatterns' => [
        'GET search' => 'search',
    ],
]

コントローラーIDのuserが、エンドポイントURLでは複数形であるusersとして表示されていることに気づかれたかもしれません。yii\rest\UrlRuleは、子URLルールを作成するときに、コントローラーIDを自動的に複数形にします。yii\rest\UrlRule::$pluralizeをfalseに設定することで、この動作を無効にできます。

情報: コントローラーIDの複数形化はyii\helpers\Inflector::pluralize()によって行われます。このメソッドは、特別な複数形化ルールを尊重します。たとえば、単語boxはboxsではなくboxesとして複数形になります。

自動的な複数形化が要件を満たさない場合は、yii\rest\UrlRule::$controllerプロパティを設定して、エンドポイントURLで使用される名前とコントローラーIDのマッピングを明示的に指定することもできます。たとえば、次のコードは名前uをコントローラーIDuserにマッピングします。

[
    'class' => 'yii\rest\UrlRule',
    'controller' => ['u' => 'user'],
]

含まれるルールの追加設定 ¶

yii\rest\UrlRuleに含まれる各ルールに適用される追加設定を指定することが役立つ場合があります。良い例としては、expandパラメーターのデフォルト値の指定があります。

[
    'class' => 'yii\rest\UrlRule',
    'controller' => ['user'],
    'ruleConfig' => [
        'class' => 'yii\web\UrlRule',
        'defaults' => [
            'expand' => 'profile',
        ]
    ],
],