From 8cfdd37475eb764caeb56559b4a068f8cae943b9 Mon Sep 17 00:00:00 2001 From: Larry Ullman Date: Mon, 18 Aug 2014 16:11:12 -0400 Subject: [PATCH] Light edits --- docs/guide/rest-rate-limiting.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/guide/rest-rate-limiting.md b/docs/guide/rest-rate-limiting.md index d7aa002..b3f1671 100644 --- a/docs/guide/rest-rate-limiting.md +++ b/docs/guide/rest-rate-limiting.md @@ -1,28 +1,28 @@ Rate Limiting ============= -To prevent abuse, you should consider adding rate limiting to your APIs. For example, you may limit the API usage +To prevent abuse, you should consider adding *rate limiting* to your APIs. For example, you may want to limit the API usage of each user to be at most 100 API calls within a period of 10 minutes. If too many requests are received from a user -within the period of the time, a response with status code 429 (meaning Too Many Requests) should be returned. +within the stated period of the time, a response with status code 429 (meaning "Too Many Requests") should be returned. To enable rate limiting, the [[yii\web\User::identityClass|user identity class]] should implement [[yii\filters\RateLimitInterface]]. -This interface requires implementation of the following three methods: +This interface requires implementation of three methods: -* `getRateLimit()`: returns the maximum number of allowed requests and the time period, e.g., `[100, 600]` means - at most 100 API calls within 600 seconds. +* `getRateLimit()`: returns the maximum number of allowed requests and the time period (e.g., `[100, 600]` means there can be at most 100 API calls within 600 seconds). * `loadAllowance()`: returns the number of remaining requests allowed and the corresponding UNIX timestamp - when the rate limit is checked last time. -* `saveAllowance()`: saves the number of remaining requests allowed and the current UNIX timestamp. + when the rate limit was last checked. +* `saveAllowance()`: saves both the number of remaining requests allowed and the current UNIX timestamp. -You may use two columns in the user table to record the allowance and timestamp information. -And `loadAllowance()` and `saveAllowance()` can then be implementation by reading and saving the values +You may want to use two columns in the user table to record the allowance and timestamp information. With those defined, then `loadAllowance()` and `saveAllowance()` can be implemented to read and save the values of the two columns corresponding to the current authenticated user. To improve performance, you may also -consider storing these information in cache or some NoSQL storage. +consider storing these pieces of information in a cache or NoSQL storage. Once the identity class implements the required interface, Yii will automatically use [[yii\filters\RateLimiter]] configured as an action filter for [[yii\rest\Controller]] to perform rate limiting check. The rate limiter -will thrown a [[yii\web\TooManyRequestsHttpException]] if rate limit is exceeded. You may configure the rate limiter -as follows in your REST controller classes, +will throw a [[yii\web\TooManyRequestsHttpException]] when the rate limit is exceeded. + +You may configure the rate limiter +as follows in your REST controller classes: ```php public function behaviors() @@ -36,9 +36,9 @@ public function behaviors() When rate limiting is enabled, by default every response will be sent with the following HTTP headers containing the current rate limiting information: -* `X-Rate-Limit-Limit`: The maximum number of requests allowed with a time period; -* `X-Rate-Limit-Remaining`: The number of remaining requests in the current time period; -* `X-Rate-Limit-Reset`: The number of seconds to wait in order to get the maximum number of allowed requests. +* `X-Rate-Limit-Limit`, the maximum number of requests allowed with a time period +* `X-Rate-Limit-Remaining`, the number of remaining requests in the current time period +* `X-Rate-Limit-Reset`, the number of seconds to wait in order to get the maximum number of allowed requests You may disable these headers by configuring [[yii\filters\RateLimiter::enableRateLimitHeaders]] to be false, -like shown in the above code example. +as shown in the above code example.