diff --git a/docs/guide-ru/README.md b/docs/guide-ru/README.md index c08eea4..28618ff 100644 --- a/docs/guide-ru/README.md +++ b/docs/guide-ru/README.md @@ -133,7 +133,7 @@ All Rights Reserved. * [Роутинг](rest-routing.md) * [Форматирование ответа](rest-response-formatting.md) * [Аутентификация](rest-authentication.md) -* [Ограничение количества запросов](rest-rate-limiting.md) +* [Ограничение частоты запросов](rest-rate-limiting.md) * [Версионирование](rest-versioning.md) * [Обработка ошибок](rest-error-handling.md) diff --git a/docs/guide-ru/rest-authentication.md b/docs/guide-ru/rest-authentication.md index 098c82d..25d2401 100644 --- a/docs/guide-ru/rest-authentication.md +++ b/docs/guide-ru/rest-authentication.md @@ -106,7 +106,7 @@ class User extends ActiveRecord implements IdentityInterface После включения аутентификации описанным выше способом при каждом запросе к API запрашиваемый контроллер будет пытаться аутентифицировать пользователя в своем методе `beforeAction()`. -Если аутентификация прошла успешно, контроллер выполнит другие проверки (ограничение на количество запросов, авторизация) +Если аутентификация прошла успешно, контроллер выполнит другие проверки (ограничение частоты запросов, авторизация) и затем выполнит действие. *Информация о подлинности аутентифицированного пользователя может быть получена из объекта `Yii::$app->user->identity`*. Если аутентификация прошла неудачно, будет возвращен ответ с HTTP-кодом состояния 401 вместе с другими необходимыми заголовками diff --git a/docs/guide-ru/rest-error-handling.md b/docs/guide-ru/rest-error-handling.md new file mode 100644 index 0000000..014a447 --- /dev/null +++ b/docs/guide-ru/rest-error-handling.md @@ -0,0 +1,44 @@ +Обработка ошибок +================ + +Если при обработке запроса к RESTful API в запросе пользователя обнаруживается ошибка или происходит +что-то непредвиденное на сервере, вы можете просто выбрасывать исключение, чтобы уведомить пользователя о нештатной ситуации. +Если же вы можете установить конкретную причину ошибки (например, запрошенный ресурс не существует), вам следует подумать +о том, чтобы выбрасывать исключение с соответствующим кодом состояния HTTP (например, [[yii\web\NotFoundHttpException]], +соответствующее коду состояния 404). Yii отправит ответ с соответствующим +HTTP-кодом и текстом. Он также включит в тело ответа сериализованное представление +исключения. Например: + +``` +HTTP/1.1 404 Not Found +Date: Sun, 02 Mar 2014 05:31:43 GMT +Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y +Transfer-Encoding: chunked +Content-Type: application/json; charset=UTF-8 + +{ + "type": "yii\\web\\NotFoundHttpException", + "name": "Not Found Exception", + "message": "The requested resource was not found.", + "code": 0, + "status": 404 +} +``` + +Сводный список кодов состояния HTTP, используемых REST-фреймворком Yii: + +* `200`: OK. Все сработало именно так, как и ожидалось. +* `201`: Ресурс был успешно создан в ответ на `POST`-запрос. Заголовок `Location` + содержит URL, указывающий на только что созданный ресурс. +* `204`: Запрос обработан успешно, и в ответе нет содержимого (для запроса `DELETE`, например). +* `304`: Ресурс не изменялся. Можно использовать закэшированную версию. +* `400`: Неверный запрос. Может быть связано с разнообразными проблемами на стороне пользователя, такими как неверные JSON-данные + в теле запроса, неправильные параметры действия, и т.д. +* `401`: Аутентификация завершилась неудачно. +* `403`: Аутентифицированному пользователю не разрешен доступ к указанной точке входа API. +* `404`: Запрошенный ресурс не существует. +* `405`: Метод не поддерживается. Сверьтесь со списком поддерживаемых HTTP-методов в заголовке `Allow`. +* `415`: Неподдерживаемый тип данных. Запрашивается неправильный тип данных или номер версии. +* `422`: Проверка данных завершилась неудачно (в ответе на `POST`-запрос, например). Подробные сообщения об ошибках смотрите в теле ответа. +* `429`: Слишком много запросов. Запрос отклонен из-за превышения ограничения частоты запросов. +* `500`: Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе. diff --git a/docs/guide-ru/rest-rate-limiting.md b/docs/guide-ru/rest-rate-limiting.md new file mode 100644 index 0000000..467b2a5 --- /dev/null +++ b/docs/guide-ru/rest-rate-limiting.md @@ -0,0 +1,44 @@ +Ограничение частоты запросов +=============================== + +Чтобы избежать злоупотреблений, вам следует подумать о добавлении ограничения частоты запросов к вашим API. Например, вы можете ограничить +использование каждого метода API, поставив для каждого пользователя ограничение: не более 100 вызовов API в течение 10 минут. Если от пользователя +приходит большее количество запросов в течение этого периода времени, будет возвращаться ответ с кодом состояния 429 (означающий «слишком много запросов»). + +Чтобы включить ограничение частоты запросов, *[[yii\web\User::identityClass|класс user identity]]* должен реализовывать интерфейс [[yii\filters\RateLimitInterface]]. +Этот интерфейс требует реализации следующих трех методов: + +* `getRateLimit()`: возвращает максимальное количество разрешенных запросов и период времени, т.е. `[100, 600]`, что означает + не более 100 вызовов API в течение 600 секунд. +* `loadAllowance()`: возвращает оставшееся количество разрешенных запросов и соответствующий *UNIX-timestamp*, + когда ограничение проверялось в последний раз. +* `saveAllowance()`: сохраняет оставшееся количество разрешенных запросов и текущий *UNIX-timestamp*. + +Вы можете также использовать два столбца в таблице пользователей для записи количества разрешенных запросов и *отметки времени*. +`loadAllowance()` и `saveAllowance()` могут быть реализованы как чтение и сохранение значений, относящихся к текущему аутентифицированному пользователю, +в этих двух столбцах. Для улучшения производительности вы можете подумать о том, чтобы хранить эту информацию +в кэше или каком-либо NoSQL-хранилище. + +Так как *identity class* реализует требуемый интерфейс, Yii будет автоматически использовать [[yii\filters\RateLimiter]], +настроенный как фильтр действий в [[yii\rest\Controller]], для выполнения проверки на количество разрешенных запросов. Если ограничение на количество +запросов будет превышено, выбрасывается исключение [[yii\web\TooManyRequestsHttpException]]. Вы можете настроить ограничитель частоты запросов +в ваших классах REST-контроллеров следующим образом: + +```php +public function behaviors() +{ + $behaviors = parent::behaviors(); + $behaviors['rateLimiter']['enableRateLimitHeaders'] = false; + return $behaviors; +} +``` + +Когда ограничение частоты запросов включено, по умолчанию каждый ответ будет возващаться со следующими HTTP-заголовками, содержащими +информацию о текущих ограничениях количества запросов: + +* `X-Rate-Limit-Limit`: максимальное количество запросов, разрешенное в течение периода времени; +* `X-Rate-Limit-Remaining`: оставшееся количество разрешенных запросов в текущем периоде времени; +* `X-Rate-Limit-Reset`: количество секунд, которое нужно подождать до получения максимального количества разрешенных запросов. + +Вы можете отключить эти заголовки, установив свойство [[yii\filters\RateLimiter::enableRateLimitHeaders]] в значение false, +как показано в примере кода выше.