Merge pull request #4699 from bevalorous/docs-guide-russian-translation

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)
 

docs/guide-ru/rest-authentication.md

@@ -106,7 +106,7 @@ class User extends ActiveRecord implements IdentityInterface
 После включения аутентификации описанным выше способом при каждом запросе к API запрашиваемый контроллер
 будет пытаться аутентифицировать пользователя в своем методе `beforeAction()`.
 
-Если аутентификация прошла успешно, контроллер выполнит другие проверки (ограничение на количество запросов, авторизация)
+Если аутентификация прошла успешно, контроллер выполнит другие проверки (ограничение частоты запросов, авторизация)
 и затем выполнит действие. *Информация о подлинности аутентифицированного пользователя может быть получена из объекта `Yii::$app->user->identity`*.
 
 Если аутентификация прошла неудачно, будет возвращен ответ с HTTP-кодом состояния 401 вместе с другими необходимыми заголовками

docs/guide-ru/rest-error-handling.md

+Обработка ошибок
+================
+
+Если при обработке запроса к 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`: Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе.

docs/guide-ru/rest-rate-limiting.md

+Ограничение частоты запросов
+===============================
+
+Чтобы избежать злоупотреблений, вам следует подумать о добавлении ограничения частоты запросов к вашим 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,
+как показано в примере кода выше.