Урок 12: REST API на Yii 2

На 12-ом уроке мы изучим одну из самых тем современной веб-разработки, это создание REST API на Yii 2. Если вы мечтаете разрабатывать мобильные приложения, SPA или интегрироваться с внешними сервисами, этот урок станет вашим надежным проводником. Мы разберем настройку приложения, создание контроллеров, аутентификацию через токены и документирование API.

Настройка RESTful-приложения

Перед тем как создавать API, важно правильно настроить Yii 2. RESTful-архитектура требует соблюдения определенных правил: использование HTTP-методов (GET, POST, PUT, DELETE), форматирование данных (JSON/XML) и удобные URL. Давайте подготовим наше приложение.

Шаг 1: Конфигурация приложения
В файле config/web.php добавим компонент urlManager и настроим его для работы с «человекопонятными» URL. Также укажем, что данные по умолчанию будут передаваться в формате JSON.

'components' => [
    'urlManager' => [
        'enablePrettyUrl' => true,
        'showScriptName' => false,
        'enableStrictParsing' => true,
        'rules' => [
            ['class' => 'yii\rest\UrlRule', 'controller' => 'api/article'],
        ],
    ],
    'request' => [
        'parsers' => [
            'application/json' => 'yii\web\JsonParser',
        ],
    ],
],

Шаг 2: Создание модуля для API
Чтобы изолировать API от остальной логики приложения, создадим модуль Api. Добавим в config/web.php:

'modules' => [
    'api' => [
        'class' => 'app\modules\api\Module',
    ],
],

Создадим структуру папок:

modules/
    api/
        controllers/
        models/

Практическая задача:
Настройте приложение для работы с REST API: добавьте urlManager, создайте модуль Api и проверьте его доступность по адресу http://ваш-сайт/api.

Создание API-контроллеров

API-контроллеры в Yii 2 наследуются от yii\rest\ActiveController, что автоматизирует базовые CRUD-операции. Рассмотрим создание контроллера для сущности «Статья».

Шаг 1: Базовый контроллер
Создадим modules/api/controllers/ArticleController.php:

namespace app\modules\api\controllers;

use yii\rest\ActiveController;

class ArticleController extends ActiveController
{
    public $modelClass = 'app\models\Article';
}

Теперь по адресу GET /api/article вы получите список статей в формате JSON.

Шаг 2: Кастомизация действий
Допустим, мы хотим добавить поиск по заголовку. Переопределим метод actions():

public function actions()
{
    $actions = parent::actions();
    $actions['index']['prepareDataProvider'] = [$this, 'prepareDataProvider'];
    return $actions;
}

public function prepareDataProvider()
{
    $searchModel = new \app\models\ArticleSearch();
    return $searchModel->search(\Yii::$app->request->queryParams);
}

Практическая задача:
Создайте контроллер UserController для управления пользователями. Добавьте действие для фильтрации по email.

Аутентификация через токены

Безопасность API критически важный аспект. Реализуем аутентификацию через JWT (JSON Web Tokens).

Шаг 1: Установка библиотеки
Установим через Composer пакет sizeg/yii2-jwt:

composer require sizeg/yii2-jwt

Шаг 2: Настройка компонента
В config/web.php добавим:

'components' => [
    'jwt' => [
        'class' => \sizeg\jwt\Jwt::class,
        'key' => 'ваш_секретный_ключ',
    ],
],

Шаг 3: Создание действия для генерации токена
Добавим в UserController:

public function actionLogin()
{
    $email = \Yii::$app->request->post('email');
    $password = \Yii::$app->request->post('password');

    $user = User::findOne(['email' => $email]);

    if ($user && $user->validatePassword($password)) {
        $jwt = \Yii::$app->jwt;
        $token = $jwt->build()
            ->setClaim('uid', $user->id)
            ->sign($jwt->getSigner(), $jwt->getKey())
            ->toString();

        return ['token' => $token];
    }

    throw new \yii\web\UnauthorizedHttpException('Неверные данные');
}

Шаг 4: Защита контроллера
Добавим поведение аутентификации в ArticleController:

use yii\filters\auth\HttpBearerAuth;

public function behaviors()
{
    $behaviors = parent::behaviors();
    $behaviors['authenticator'] = [
        'class' => HttpBearerAuth::class,
        'except' => ['index', 'view'], // Разрешаем доступ без токена
    ];
    return $behaviors;
}

Практическая задача:
Реализуйте аутентификацию для UserController. Проверьте доступ к защищенным методам через Postman.

Документирование API с помощью Swagger

Swagger (OpenAPI) это стандарт для описания API. Интегрируем его в Yii 2.

Шаг 1: Установка пакета
Установим zircote/swagger-php и darkaonline/yii2-swagger:

composer require zircote/swagger-php darkaonline/yii2-swagger

Шаг 2: Настройка модуля
В config/web.php:

'modules' => [
    'swagger' => [
        'class' => 'darkaonline\swagger\SwaggerModule',
        'jsonPath' => '@app/web/docs/swagger.json',
        'host' => 'ваш-сайт',
    ],
],

Шаг 3: Добавление аннотаций
Документируем метод actionLogin в UserController:

/**
 * @OA\Post(
 *     path="/api/user/login",
 *     tags={"Auth"},
 *     summary="Авторизация пользователя",
 *     @OA\RequestBody(
 *         @OA\MediaType(
 *             mediaType="application/json",
 *             @OA\Schema(
 *                 @OA\Property(property="email", type="string"),
 *                 @OA\Property(property="password", type="string"),
 *             )
 *         )
 *     ),
 *     @OA\Response(response="200", description="Успешная авторизация"),
 *     @OA\Response(response="401", description="Ошибка")
 * )
 */
public function actionLogin() { ... }

Шаг 4: Генерация документации
Создадим команду для генерации swagger.json:

php ./vendor/bin/openapi modules/api -o web/docs

Практическая задача:
Добавьте документацию для ArticleController и проверьте ее отображение в Swagger UI по адресу /swagger.

Заключение

Сегодня мы прошли ключевые этапы создания REST API на Yii 2. Вы научились настраивать приложение, создавать контроллеры, защищать API токенами и документировать его. Эти навыки пригодятся вам в реальных проектах, от мобильных приложений до микросервисных архитектур.

Попробуйте расширить функционал:

1. Добавьте пагинацию в список статей.
2. Реализуйте ролевую модель доступа (RBAC).
3. Настройте кеширование ответов API.

Полный курс с уроками по Yii 2 для начинающих доступен здесь: https://max-gabov.ru/yii-2-dlya-nachinaushih