Полное руководство по Yii 2.0

Версионирование

Хороший API должен быть версионирован: изменения и новые возможности реализуются в новых версиях API, а не в одной и той же версии. В отличие от Web-приложений, где у вас есть полный контроль и над серверным, и над клиентским кодом, API используются клиентами, код которых вы не контролируете. Поэтому, обратная совместимость (BC) должна по возможности сохраняться. Если ломающее её изменение необходимо, делать его нужно в новой версии API. Существующие клиенты могут продолжать использовать старую, совместимую с ними версию API. Новые или обновлённые клиенты могут использовать новую версию.

Ограничение частоты запросов

Чтобы избежать злоупотреблений, вам следует подумать о добавлении ограничения частоты запросов к вашим API. Например, вы можете ограничить использование API до 100 вызовов в течение 10 минут для каждого пользователя. Если от пользователя в течение этого периода времени приходит большее количество запросов, будет возвращаться ответ с кодом состояния 429 («слишком много запросов»).

Форматирование ответа

При обработке RESTful API запросов приложение обычно выполняет следующие шаги, связанные с форматированием ответа:

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

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

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

Контроллеры

После создания классов ресурсов и настройки способа форматирования ресурсных данных следующим шагом является создание действий контроллеров для предоставления ресурсов конечным пользователям через RESTful API.

В Yii есть два базовых класса контроллеров для упрощения вашей работы по созданию RESTful-действий: [[yii\rest\Controller]] и [[yii\rest\ActiveController]]. Разница между этими двумя контроллерами в том, что у последнего есть набор действий по умолчанию, который специально создан для работы с ресурсами, представленными Active Record. Так что если вы используете Active Record и вас устраивает предоставленный набор встроенных действий, вы можете унаследовать классы ваших контроллеров от [[yii\rest\ActiveController]], что позволит вам создать полноценные RESTful API, написав минимум кода.

Ресурсы

RESTful API строятся вокруг доступа к ресурсам и управления ими. Вы можете думать о ресурсах как о моделях из MVC.

Хотя не существует никаких ограничений на то, как представить ресурс, в Yii ресурсы обычно представляются как объекты [[yii\base\Model]] или дочерние классы (например [[yii\db\ActiveRecord]]), потому как:

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

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

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

HTTP кэширование

Кроме серверного кэширования, которое мы описали в предыдущих разделах, веб-приложения также могут использовать кэширование на стороне клиента, чтобы сэкономить время для формирования и передачи одного и того же содержания страницы.

Чтобы использовать кэширование на стороне клиента, вы можете настроить [[yii\filters\HttpCache]] в качестве фильтра для действия контроллера, отображающего результат, который может быть закэширован на стороне клиента. [[yii\filters\HttpCache|HttpCache]] работает только для GET и HEAD запросов. Для этих запросов он может обрабатывать три вида HTTP заголовков, относящихся к кэшированию:

Кэширование страниц

Кэширование страниц — это кэширование всего содержимого страницы на стороне сервера. Позже, когда эта страница будет снова запрошена, сервер вернет её из кэша вместо того чтобы генерировать её заново.

Кэширование страниц осуществляется при помощи фильтра действия [[yii\filters\PageCache]] и может быть использовано в классе контроллера следующим образом: