RESTful Web Services

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

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

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

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

Включение JSON Input

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

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

Пробуем это

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

  • GET/users: список всех пользователей за страницей;
  • HEAD/users: показать обзорную информацию о листинге пользователя;
  • POST/users: создать нового пользователя;
  • GET/users/123: вернуть информацию о пользователе 123;
  • HEAD/users/123: показать обзорную информацию пользователя 123;
  • PATCH/users/ 23 и 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 Yii RESTful, вы реализуете оконечную точку API в терминах действия контроллера и используете контроллер для организации действий, которые реализуют конечные точки для одного типа ресурсов.

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

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