API RESTful - Маршрутизация

Имея готовые классы ресурсов и контроллеров, вы можете получить доступ к ресурсам, используя URL, например http://localhost/index.php?r=user/create, аналогично тому, что вы можете делать с обычными веб-приложениями.

На практике вы обычно хотите включить красивые URL-адреса и использовать HTTP-команды. Например, запрос POST/users будет означать доступ к действию user/create. Это можно сделать легко, настроив компонент приложения urlManager в конфигурации приложения следующим образом:

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

По сравнению с управлением URL-адресами для веб-приложений главное нововведение - использование yii\rest\UrlRule для маршрутизации запросов RESTful API. Этот специальный класс правил 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, чтобы переопределить существующие шаблоны или добавить новые шаблоны, поддерживаемые этим правилом. Например, чтобы поддерживать новый search действия конечной точкой GET /users/search, настройте параметр extraPatterns следующим образом:

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

Возможно, вы заметили, что пользователь идентификатора контроллера отображается во множественном числе как пользователи в URL-адресах конечных точек. Это происходит потому, что yii\rest\UrlRule автоматически плюрализирует идентификаторы контроллеров при создании дочерних URL-правил. Вы можете отключить это поведение, установив yii\rest\UrlRule::$pluralize в false.

В случае, если автоматическое плюрализация не соответствует вашим требованиям, вы также можете настроить свойство yii\rest\UrlRule::$controller, чтобы явно указать, как сопоставить имя, используемое в URL-адресах конечных точек, с идентификатором контроллера. Например, следующий код отображает имя u для пользователя ID контроллера.

[
    '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',
        ]
    ],
],