Маршрутизация

После подготовки классов ресурсов и контроллеров, вы можете получить доступ к ресурсам используя 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',
    ],
]

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

Информация: Обработка множественного числа идентификаторов контроллеров выполняется методом yii\helpers\Inflector::pluralize(). Метод учитывает особые правила склонения. Например, слово box будет склоняться к множественному числу как boxes вместо boxs.

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

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