You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "kayx23 (via GitHub)" <gi...@apache.org> on 2024/12/30 08:08:37 UTC

[PR] docs: improve `limit-req` plugin docs [apisix]

kayx23 opened a new pull request, #11873:
URL: https://github.com/apache/apisix/pull/11873

   ### Description
   
   Improve `limit-req` plugin docs.
   
   ### Checklist
   
   - [x] I have explained the need for this PR and the problem it solves
   - [x] I have explained the changes or the new features added to this PR
   - [ ] I have added tests corresponding to this change
   - [x] I have updated the documentation to reflect this change
   - [ ] I have verified that this change is backward compatible (If not, please discuss on the [APISIX mailing list](https://github.com/apache/apisix/tree/master#community) first)
   
   <!--
   
   Note
   
   1. Mark the PR as draft until it's ready to be reviewed.
   2. Always add/update tests for any changes unless you have a good reason.
   3. Always update the documentation to reflect the changes made in the PR.
   4. Make a new commit to resolve conversations instead of `push -f`.
   5. To resolve merge conflicts, merge master instead of rebasing.
   6. Use "request review" to notify the reviewer after making changes.
   7. Only a reviewer can mark a conversation as resolved.
   
   -->
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] docs: improve `limit-req` plugin docs [apisix]

Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on code in PR #11873:
URL: https://github.com/apache/apisix/pull/11873#discussion_r1980878228


##########
docs/en/latest/plugins/limit-req.md:
##########
@@ -68,177 +72,213 @@ You can fetch the `admin_key` from `config.yaml` and save to an environment vari
 admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
 ```
 
-:::
+### Apply Rate Limiting by Remote Address
+
+The following example demonstrates the rate limiting of HTTP requests by a single variable, `remote_addr`.
+
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '
+  {
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var",
-            "key": "remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "remote_addr",
+        "key_type": "var",
+        "rejected_code": 429,
+        "nodelay": true
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Send a request to verify:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-You can also configure the `key_type` to `var_combination` as shown:
+You should see an `HTTP/1.1 200 OK` response.
+
+The request has consumed all the quota allowed for the time window. If you send the request again within the same second, you should receive an `HTTP/1.1 429 Too Many Requests` response, indicating the request surpasses the quota threshold.
+
+### Implement API Throttling
+
+The following example demonstrates how to configure `burst` to allow overrun of the rate limiting threshold by the configured value and achieve request throttling. You will also see a comparison against when throttling is not implemented.
 
-```json
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address, with a `burst` of 1 to allow for 1 request exceeding the `rate` to be delayed for processing:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var_combination",
-            "key": "$consumer_name $remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 1,
+        "key": "remote_addr",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}
+  }'
 ```
 
-You can also configure the Plugin on specific consumers to limit their requests.
-
-First, you can create a Consumer and enable the `limit-req` Plugin on it:
+Generate three requests to the route:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "username": "consumer_jack",
-    "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        },
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 403,
-            "key": "consumer_name"
-        }
-    }
-}'
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
 ```
 
-In this example, the [key-auth](./key-auth.md) Plugin is used to authenticate the Consumer.
+You are likely to see that all three requests are successful:
 
-Next, create a Route and enable the `key-auth` Plugin:
+```text
+200 responses: 3 ; 429 responses: 0
+```
+
+To see the effect without `burst`, update `burst` to 0 or set `nodelay` to `true` as follows:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes/limit-req-route" -X PATCH \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
     "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        }
-    },
-    "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "limit-req": {
+        "nodelay": true
+      }
     }
-}'
+  }'
+```
+
+Generate three requests to the Route again:
+
+```shell
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
+```
+
+You should see a response similar to the following, showing requests surpassing the rate have been rejected:
+
+```text
+200 responses: 1 ; 429 responses: 2
 ```
 
-## Example usage
+### Apply Rate Limiting by Remote Address and Consumer Name
+
+The following example demonstrates the rate limiting of requests by a combination of variables, `remote_addr` and `consumer_name`.
 
-Once you have configured the Plugin as shown above, you can test it out. The above configuration limits to 3 request per second. If the number of requests is greater than 3 but less than 5, a delay will be added. And if the number of requests per second exceeds 5, it will be rejected.
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address and for each Consumer.
 
-Now if you send a request:
+Create a Consumer `john`:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "john"
+  }'
 ```
 
-For authenticated requests:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html -H 'apikey: auth-jack'
+curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-john-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "john-key"
+      }
+    }
+  }'
 ```
 
-If you exceed the limit, you will receive a response with a 503 code:
-
-```html
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
+Create a second Consumer `jane`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "jane"
+  }'
 ```
 
-You can set a custom rejected message by configuring the `rejected_msg` attribute. You will then receive a response like:
+Create `key-auth` Credential for the consumer:

Review Comment:
   ```suggestion
   Create `key-auth` Credential for the Consumer:
   ```



##########
docs/en/latest/plugins/limit-req.md:
##########
@@ -68,177 +72,213 @@ You can fetch the `admin_key` from `config.yaml` and save to an environment vari
 admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
 ```
 
-:::
+### Apply Rate Limiting by Remote Address
+
+The following example demonstrates the rate limiting of HTTP requests by a single variable, `remote_addr`.
+
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '
+  {
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var",
-            "key": "remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "remote_addr",
+        "key_type": "var",
+        "rejected_code": 429,
+        "nodelay": true
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Send a request to verify:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-You can also configure the `key_type` to `var_combination` as shown:
+You should see an `HTTP/1.1 200 OK` response.
+
+The request has consumed all the quota allowed for the time window. If you send the request again within the same second, you should receive an `HTTP/1.1 429 Too Many Requests` response, indicating the request surpasses the quota threshold.
+
+### Implement API Throttling
+
+The following example demonstrates how to configure `burst` to allow overrun of the rate limiting threshold by the configured value and achieve request throttling. You will also see a comparison against when throttling is not implemented.
 
-```json
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address, with a `burst` of 1 to allow for 1 request exceeding the `rate` to be delayed for processing:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var_combination",
-            "key": "$consumer_name $remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 1,
+        "key": "remote_addr",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}
+  }'
 ```
 
-You can also configure the Plugin on specific consumers to limit their requests.
-
-First, you can create a Consumer and enable the `limit-req` Plugin on it:
+Generate three requests to the route:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "username": "consumer_jack",
-    "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        },
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 403,
-            "key": "consumer_name"
-        }
-    }
-}'
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
 ```
 
-In this example, the [key-auth](./key-auth.md) Plugin is used to authenticate the Consumer.
+You are likely to see that all three requests are successful:
 
-Next, create a Route and enable the `key-auth` Plugin:
+```text
+200 responses: 3 ; 429 responses: 0
+```
+
+To see the effect without `burst`, update `burst` to 0 or set `nodelay` to `true` as follows:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes/limit-req-route" -X PATCH \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
     "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        }
-    },
-    "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "limit-req": {
+        "nodelay": true
+      }
     }
-}'
+  }'
+```
+
+Generate three requests to the Route again:
+
+```shell
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
+```
+
+You should see a response similar to the following, showing requests surpassing the rate have been rejected:
+
+```text
+200 responses: 1 ; 429 responses: 2
 ```
 
-## Example usage
+### Apply Rate Limiting by Remote Address and Consumer Name
+
+The following example demonstrates the rate limiting of requests by a combination of variables, `remote_addr` and `consumer_name`.
 
-Once you have configured the Plugin as shown above, you can test it out. The above configuration limits to 3 request per second. If the number of requests is greater than 3 but less than 5, a delay will be added. And if the number of requests per second exceeds 5, it will be rejected.
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address and for each Consumer.
 
-Now if you send a request:
+Create a Consumer `john`:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "john"
+  }'
 ```
 
-For authenticated requests:
+Create `key-auth` Credential for the consumer:

Review Comment:
   ```suggestion
   Create `key-auth` Credential for the Consumer:
   ```



##########
docs/en/latest/plugins/limit-req.md:
##########
@@ -68,177 +72,213 @@ You can fetch the `admin_key` from `config.yaml` and save to an environment vari
 admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
 ```
 
-:::
+### Apply Rate Limiting by Remote Address
+
+The following example demonstrates the rate limiting of HTTP requests by a single variable, `remote_addr`.
+
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '
+  {
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var",
-            "key": "remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "remote_addr",
+        "key_type": "var",
+        "rejected_code": 429,
+        "nodelay": true
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Send a request to verify:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-You can also configure the `key_type` to `var_combination` as shown:
+You should see an `HTTP/1.1 200 OK` response.
+
+The request has consumed all the quota allowed for the time window. If you send the request again within the same second, you should receive an `HTTP/1.1 429 Too Many Requests` response, indicating the request surpasses the quota threshold.
+
+### Implement API Throttling
+
+The following example demonstrates how to configure `burst` to allow overrun of the rate limiting threshold by the configured value and achieve request throttling. You will also see a comparison against when throttling is not implemented.
 
-```json
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address, with a `burst` of 1 to allow for 1 request exceeding the `rate` to be delayed for processing:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var_combination",
-            "key": "$consumer_name $remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 1,
+        "key": "remote_addr",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}
+  }'
 ```
 
-You can also configure the Plugin on specific consumers to limit their requests.
-
-First, you can create a Consumer and enable the `limit-req` Plugin on it:
+Generate three requests to the route:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "username": "consumer_jack",
-    "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        },
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 403,
-            "key": "consumer_name"
-        }
-    }
-}'
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
 ```
 
-In this example, the [key-auth](./key-auth.md) Plugin is used to authenticate the Consumer.
+You are likely to see that all three requests are successful:
 
-Next, create a Route and enable the `key-auth` Plugin:
+```text
+200 responses: 3 ; 429 responses: 0
+```
+
+To see the effect without `burst`, update `burst` to 0 or set `nodelay` to `true` as follows:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes/limit-req-route" -X PATCH \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
     "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        }
-    },
-    "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "limit-req": {
+        "nodelay": true
+      }
     }
-}'
+  }'
+```
+
+Generate three requests to the Route again:
+
+```shell
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
+```
+
+You should see a response similar to the following, showing requests surpassing the rate have been rejected:
+
+```text
+200 responses: 1 ; 429 responses: 2
 ```
 
-## Example usage
+### Apply Rate Limiting by Remote Address and Consumer Name
+
+The following example demonstrates the rate limiting of requests by a combination of variables, `remote_addr` and `consumer_name`.
 
-Once you have configured the Plugin as shown above, you can test it out. The above configuration limits to 3 request per second. If the number of requests is greater than 3 but less than 5, a delay will be added. And if the number of requests per second exceeds 5, it will be rejected.
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address and for each Consumer.
 
-Now if you send a request:
+Create a Consumer `john`:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "john"
+  }'
 ```
 
-For authenticated requests:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html -H 'apikey: auth-jack'
+curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-john-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "john-key"
+      }
+    }
+  }'
 ```
 
-If you exceed the limit, you will receive a response with a 503 code:
-
-```html
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
+Create a second Consumer `jane`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "jane"
+  }'
 ```
 
-You can set a custom rejected message by configuring the `rejected_msg` attribute. You will then receive a response like:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-{"error_msg":"Requests are too frequent, please try again later."}
+curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-jane-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "jane-key"
+      }
+    }
+  }'
 ```
 
-## Delete Plugin
-
-To remove the `limit-req` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+Create a Route with `key-auth` and `limit-req` plugins, and specify in the `limit-req` Plugin to use a combination of variables as the rate limiting key:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
-    "id": 1,
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
+      "key-auth": {},
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "$remote_addr $consumer_name",
+        "key_type": "var_combination",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
 ```
 
-Similarly for removing the Plugin from a Consumer:
+Send two requests simultaneously, each for one consumer:

Review Comment:
   ```suggestion
   Send two requests simultaneously, each for one Consumer:
   ```



##########
docs/en/latest/plugins/limit-req.md:
##########
@@ -68,177 +72,213 @@ You can fetch the `admin_key` from `config.yaml` and save to an environment vari
 admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
 ```
 
-:::
+### Apply Rate Limiting by Remote Address
+
+The following example demonstrates the rate limiting of HTTP requests by a single variable, `remote_addr`.
+
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '
+  {
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var",
-            "key": "remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "remote_addr",
+        "key_type": "var",
+        "rejected_code": 429,
+        "nodelay": true
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Send a request to verify:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-You can also configure the `key_type` to `var_combination` as shown:
+You should see an `HTTP/1.1 200 OK` response.
+
+The request has consumed all the quota allowed for the time window. If you send the request again within the same second, you should receive an `HTTP/1.1 429 Too Many Requests` response, indicating the request surpasses the quota threshold.
+
+### Implement API Throttling
+
+The following example demonstrates how to configure `burst` to allow overrun of the rate limiting threshold by the configured value and achieve request throttling. You will also see a comparison against when throttling is not implemented.
 
-```json
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address, with a `burst` of 1 to allow for 1 request exceeding the `rate` to be delayed for processing:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var_combination",
-            "key": "$consumer_name $remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 1,
+        "key": "remote_addr",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}
+  }'
 ```
 
-You can also configure the Plugin on specific consumers to limit their requests.
-
-First, you can create a Consumer and enable the `limit-req` Plugin on it:
+Generate three requests to the route:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "username": "consumer_jack",
-    "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        },
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 403,
-            "key": "consumer_name"
-        }
-    }
-}'
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
 ```
 
-In this example, the [key-auth](./key-auth.md) Plugin is used to authenticate the Consumer.
+You are likely to see that all three requests are successful:
 
-Next, create a Route and enable the `key-auth` Plugin:
+```text
+200 responses: 3 ; 429 responses: 0
+```
+
+To see the effect without `burst`, update `burst` to 0 or set `nodelay` to `true` as follows:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes/limit-req-route" -X PATCH \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
     "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        }
-    },
-    "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "limit-req": {
+        "nodelay": true
+      }
     }
-}'
+  }'
+```
+
+Generate three requests to the Route again:
+
+```shell
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
+```
+
+You should see a response similar to the following, showing requests surpassing the rate have been rejected:
+
+```text
+200 responses: 1 ; 429 responses: 2
 ```
 
-## Example usage
+### Apply Rate Limiting by Remote Address and Consumer Name
+
+The following example demonstrates the rate limiting of requests by a combination of variables, `remote_addr` and `consumer_name`.
 
-Once you have configured the Plugin as shown above, you can test it out. The above configuration limits to 3 request per second. If the number of requests is greater than 3 but less than 5, a delay will be added. And if the number of requests per second exceeds 5, it will be rejected.
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address and for each Consumer.
 
-Now if you send a request:
+Create a Consumer `john`:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "john"
+  }'
 ```
 
-For authenticated requests:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html -H 'apikey: auth-jack'
+curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-john-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "john-key"
+      }
+    }
+  }'
 ```
 
-If you exceed the limit, you will receive a response with a 503 code:
-
-```html
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
+Create a second Consumer `jane`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "jane"
+  }'
 ```
 
-You can set a custom rejected message by configuring the `rejected_msg` attribute. You will then receive a response like:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-{"error_msg":"Requests are too frequent, please try again later."}
+curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-jane-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "jane-key"
+      }
+    }
+  }'
 ```
 
-## Delete Plugin
-
-To remove the `limit-req` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+Create a Route with `key-auth` and `limit-req` plugins, and specify in the `limit-req` Plugin to use a combination of variables as the rate limiting key:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
-    "id": 1,
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
+      "key-auth": {},
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "$remote_addr $consumer_name",
+        "key_type": "var_combination",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
 ```
 
-Similarly for removing the Plugin from a Consumer:
+Send two requests simultaneously, each for one consumer:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "username": "consumer_jack",
-    "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        }
-    }
-}'
+curl -i "http://127.0.0.1:9080/get" -H 'apikey: jane-key' & \
+curl -i "http://127.0.0.1:9080/get" -H 'apikey: john-key' &
 ```
+
+You should receive `HTTP/1.1 200 OK` for both requests, indicating the request has not exceeded the threshold for each consumer.

Review Comment:
   ```suggestion
   You should receive `HTTP/1.1 200 OK` for both requests, indicating the request has not exceeded the threshold for each Consumer.
   ```



##########
docs/en/latest/plugins/limit-req.md:
##########
@@ -68,177 +72,213 @@ You can fetch the `admin_key` from `config.yaml` and save to an environment vari
 admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
 ```
 
-:::
+### Apply Rate Limiting by Remote Address
+
+The following example demonstrates the rate limiting of HTTP requests by a single variable, `remote_addr`.
+
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '
+  {
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var",
-            "key": "remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "remote_addr",
+        "key_type": "var",
+        "rejected_code": 429,
+        "nodelay": true
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Send a request to verify:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-You can also configure the `key_type` to `var_combination` as shown:
+You should see an `HTTP/1.1 200 OK` response.
+
+The request has consumed all the quota allowed for the time window. If you send the request again within the same second, you should receive an `HTTP/1.1 429 Too Many Requests` response, indicating the request surpasses the quota threshold.
+
+### Implement API Throttling
+
+The following example demonstrates how to configure `burst` to allow overrun of the rate limiting threshold by the configured value and achieve request throttling. You will also see a comparison against when throttling is not implemented.
 
-```json
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address, with a `burst` of 1 to allow for 1 request exceeding the `rate` to be delayed for processing:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var_combination",
-            "key": "$consumer_name $remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 1,
+        "key": "remote_addr",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}
+  }'
 ```
 
-You can also configure the Plugin on specific consumers to limit their requests.
-
-First, you can create a Consumer and enable the `limit-req` Plugin on it:
+Generate three requests to the route:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "username": "consumer_jack",
-    "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        },
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 403,
-            "key": "consumer_name"
-        }
-    }
-}'
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
 ```
 
-In this example, the [key-auth](./key-auth.md) Plugin is used to authenticate the Consumer.
+You are likely to see that all three requests are successful:
 
-Next, create a Route and enable the `key-auth` Plugin:
+```text
+200 responses: 3 ; 429 responses: 0
+```
+
+To see the effect without `burst`, update `burst` to 0 or set `nodelay` to `true` as follows:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes/limit-req-route" -X PATCH \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
     "plugins": {
-        "key-auth": {
-            "key": "auth-jack"
-        }
-    },
-    "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "limit-req": {
+        "nodelay": true
+      }
     }
-}'
+  }'
+```
+
+Generate three requests to the Route again:
+
+```shell
+resp=$(seq 3 | xargs -I{} curl -i "http://127.0.0.1:9080/get" -o /dev/null -s -w "%{http_code}\n") && \
+  count_200=$(echo "$resp" | grep "200" | wc -l) && \
+  count_429=$(echo "$resp" | grep "429" | wc -l) && \
+  echo "200 responses: $count_200 ; 429 responses: $count_429"
+```
+
+You should see a response similar to the following, showing requests surpassing the rate have been rejected:
+
+```text
+200 responses: 1 ; 429 responses: 2
 ```
 
-## Example usage
+### Apply Rate Limiting by Remote Address and Consumer Name
+
+The following example demonstrates the rate limiting of requests by a combination of variables, `remote_addr` and `consumer_name`.
 
-Once you have configured the Plugin as shown above, you can test it out. The above configuration limits to 3 request per second. If the number of requests is greater than 3 but less than 5, a delay will be added. And if the number of requests per second exceeds 5, it will be rejected.
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address and for each Consumer.
 
-Now if you send a request:
+Create a Consumer `john`:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "john"
+  }'
 ```
 
-For authenticated requests:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-curl -i http://127.0.0.1:9080/index.html -H 'apikey: auth-jack'
+curl "http://127.0.0.1:9180/apisix/admin/consumers/john/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-john-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "john-key"
+      }
+    }
+  }'
 ```
 
-If you exceed the limit, you will receive a response with a 503 code:
-
-```html
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
+Create a second Consumer `jane`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "username": "jane"
+  }'
 ```
 
-You can set a custom rejected message by configuring the `rejected_msg` attribute. You will then receive a response like:
+Create `key-auth` Credential for the consumer:
 
 ```shell
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-{"error_msg":"Requests are too frequent, please try again later."}
+curl "http://127.0.0.1:9180/apisix/admin/consumers/jane/credentials" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "cred-jane-key-auth",
+    "plugins": {
+      "key-auth": {
+        "key": "jane-key"
+      }
+    }
+  }'
 ```
 
-## Delete Plugin
-
-To remove the `limit-req` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+Create a Route with `key-auth` and `limit-req` plugins, and specify in the `limit-req` Plugin to use a combination of variables as the rate limiting key:

Review Comment:
   ```suggestion
   Create a Route with `key-auth` and `limit-req` Plugins, and specify in the `limit-req` Plugin to use a combination of variables as the rate-limiting key:
   ```



##########
docs/en/latest/plugins/limit-req.md:
##########
@@ -68,177 +72,213 @@ You can fetch the `admin_key` from `config.yaml` and save to an environment vari
 admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
 ```
 
-:::
+### Apply Rate Limiting by Remote Address
+
+The following example demonstrates the rate limiting of HTTP requests by a single variable, `remote_addr`.
+
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '
+  {
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var",
-            "key": "remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 0,
+        "key": "remote_addr",
+        "key_type": "var",
+        "rejected_code": 429,
+        "nodelay": true
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Send a request to verify:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-You can also configure the `key_type` to `var_combination` as shown:
+You should see an `HTTP/1.1 200 OK` response.
+
+The request has consumed all the quota allowed for the time window. If you send the request again within the same second, you should receive an `HTTP/1.1 429 Too Many Requests` response, indicating the request surpasses the quota threshold.
+
+### Implement API Throttling
+
+The following example demonstrates how to configure `burst` to allow overrun of the rate limiting threshold by the configured value and achieve request throttling. You will also see a comparison against when throttling is not implemented.
 
-```json
-{
-    "methods": ["GET"],
-    "uri": "/index.html",
+Create a Route with `limit-req` Plugin that allows for 1 QPS per remote address, with a `burst` of 1 to allow for 1 request exceeding the `rate` to be delayed for processing:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "limit-req-route",
+    "uri": "/get",
     "plugins": {
-        "limit-req": {
-            "rate": 3,
-            "burst": 2,
-            "rejected_code": 503,
-            "key_type": "var_combination",
-            "key": "$consumer_name $remote_addr"
-        }
+      "limit-req": {
+        "rate": 1,
+        "burst": 1,
+        "key": "remote_addr",
+        "rejected_code": 429
+      }
     },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:9001": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}
+  }'
 ```
 
-You can also configure the Plugin on specific consumers to limit their requests.
-
-First, you can create a Consumer and enable the `limit-req` Plugin on it:
+Generate three requests to the route:

Review Comment:
   ```suggestion
   Generate three requests to the Route:
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] docs: improve `limit-req` plugin docs [apisix]

Posted by "moonming (via GitHub)" <gi...@apache.org>.
moonming merged PR #11873:
URL: https://github.com/apache/apisix/pull/11873


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org