Быстрый старт

Yii предоставляет целый набор инструментов для упрощения задачи реализации RESTful веб-сервисов. В частности, Yii поддерживает следующие функции RESTful API:

• Быстрое прототипирование с поддержкой распространённых API для Active Record;
• Переговоры о формате ответа (по умолчанию поддерживаются JSON и XML);
• Настраиваемая сериализация объектов с поддержкой выбора выходных полей;
• Правильное форматирование данных коллекций и ошибок валидации;
• Поддержка HATEOAS;
• Эффективное маршрутизирование с проверкой HTTP-глаголов;
• Встроенная поддержка глаголов OPTIONS и HEAD;
• Аутентификация и авторизация;
• Кэширование данных и кэширование HTTP;
• Ограничение скорости;

В дальнейшем мы используем пример, чтобы проиллюстрировать, как можно создать набор RESTful API с минимальными усилиями.

Предположим, вы хотите экспонировать данные пользователя через RESTful API. Данные пользователя хранятся в таблице user базы данных, и вы уже создали класс активной записи 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'],
    ],
]

Вышеприведённая конфигурация в основном добавляет правило URL для контроллера user, чтобы данные пользователя можно было получить и обработать с помощью красивых URL и осмысленных HTTP-глаголов.

Примечание: Yii автоматически делает множественное число для имён контроллеров для использования в конечных точках (см. раздел «Пробный запуск» ниже). Вы можете настроить это с помощью свойства yii\rest\UrlRule::$pluralize.

Включение ввода JSON

Чтобы API принимал данные в формате JSON, настройте свойство parsers компонента request приложения для использования yii\web\JsonParser для ввода JSON:

'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.

Вы можете получить доступ к своим API с помощью команды curl следующим образом,

$ curl -i -H "Accept:application/json" "http://localhost/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/json; charset=UTF-8

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

Попробуйте изменить допустимый тип содержимого на application/xml, и вы увидите, что результат возвращается в формате XML:

$ curl -i -H "Accept:application/xml" "http://localhost/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>

Следующая команда создаст нового пользователя, отправив POST-запрос с данными пользователя в формате JSON:

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

HTTP/1.1 201 Created
...
Location: http://localhost/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}

Совет: Вы также можете получить доступ к своим API через веб-браузер, введя URL http://localhost/users. Однако вам могут потребоваться некоторые плагины браузера для отправки определённых заголовков запроса.

Как вы можете видеть, в заголовках ответа есть информация о общем количестве, количестве страниц и т.д. Также есть ссылки, позволяющие переходить на другие страницы данных. Например, http://localhost/users?page=2 даст вам следующую страницу данных пользователей.

Используя параметры fields и expand, вы также можете указать, какие поля должны быть включены в результат. Например, URL http://localhost/users?fields=id,email вернёт только поля id и email.

Информация: Вы могли заметить, что результат http://localhost/users включает некоторые конфиденциальные поля, такие как password_hash и auth_key. Вы определённо не хотите, чтобы они появлялись в вашем результатах API. Вы можете и должны отфильтровать эти поля, как описано в разделе Ресурсы.

Заключение

Используя Yii RESTful API фреймворк, вы реализуете конечную точку API в терминах действия контроллера, и используете контроллер для организации действий, которые реализуют конечные точки для одного типа ресурса.

Ресурсы представляются в виде моделей данных, которые наследуются от класса yii\base\Model. Если вы работаете с базами данных (реляционными или NoSQL), рекомендуется использовать ActiveRecord для представления ресурсов.

Вы можете использовать yii\rest\UrlRule для упрощения маршрутизации к конечным точкам вашего API.

Хотя это не обязательно, рекомендуется разрабатывать RESTful API как отдельное приложение, отличное от вашего веб-фронтенда и бэкенда, для лучшей поддержки.