Skip to content

Commit 9441c2c

Browse files
pedrosousapedrosousa
committed
Update rate limiting rules API examples
1 parent fd8d08e commit 9441c2c

File tree

1 file changed

+94
-102
lines changed

1 file changed

+94
-102
lines changed

‎src/content/docs/waf/rate-limiting-rules/create-api.mdx‎

Lines changed: 94 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ head:
99
content: Create a rate limiting rule via API
1010
---
1111

12-
import { Render } from "~/components";
12+
import { Render, APIRequest } from "~/components";
1313

1414
Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create a rate limiting rule via API.
1515

@@ -32,129 +32,121 @@ Rate limiting rules must appear at the end of the rules list.
3232

3333
### Example A - Rate limiting based on request properties
3434

35-
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `{zone_id}`. The phase entry point ruleset already exists, with ID `{ruleset_id}`.
36-
37-
```bash
38-
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
39-
--header "Authorization: Bearer <API_TOKEN>" \
40-
--header "Content-Type: application/json" \
41-
--data '{
42-
"description": "My rate limiting rule",
43-
"expression": "(http.request.uri.path matches \"^/api/\")",
44-
"action": "block",
45-
"ratelimit": {
46-
"characteristics": [
47-
"cf.colo.id",
48-
"ip.src",
49-
"http.request.headers[\"x-api-key\"]"
50-
],
51-
"period": 60,
52-
"requests_per_period": 100,
53-
"mitigation_timeout": 600
54-
}
55-
}'
56-
```
35+
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `$ZONE_ID`. The phase entry point ruleset already exists, with ID `$RULESET_ID`.
36+
37+
<APIRequest
38+
path="/zones/{zone_id}/rulesets/{ruleset_id}/rules"
39+
method="POST"
40+
json={{
41+
description: "My rate limiting rule",
42+
expression: '(http.request.uri.path matches "^/api/")',
43+
action: "block",
44+
ratelimit: {
45+
characteristics: [
46+
"cf.colo.id",
47+
"ip.src",
48+
'http.request.headers["x-api-key"]',
49+
],
50+
period: 60,
51+
requests_per_period: 100,
52+
mitigation_timeout: 600,
53+
},
54+
}}
55+
/>
5756

5857
<Render file="api-create-ruleset-with-rule" />
5958

6059
### Example B - Rate limiting with a custom response
6160

62-
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `{zone_id}`. The phase entry point ruleset already exists, with ID `{ruleset_id}`.
61+
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `$ZONE_ID`. The phase entry point ruleset already exists, with ID `$RULESET_ID`.
6362

6463
The new rule defines a [custom response](/waf/rate-limiting-rules/create-zone-dashboard/#configure-a-custom-response-for-blocked-requests) for requests blocked due to rate limiting.
6564

66-
```bash null {9-13}
67-
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
68-
--header "Authorization: Bearer <API_TOKEN>" \
69-
--header "Content-Type: application/json" \
70-
--data '{
71-
"description": "My rate limiting rule",
72-
"expression": "(http.request.uri.path matches \"^/api/\")",
73-
"action": "block",
74-
"action_parameters": {
75-
"response": {
76-
"status_code": 403,
77-
"content": "You have been rate limited.",
78-
"content_type": "text/plain"
79-
}
80-
},
81-
"ratelimit": {
82-
"characteristics": [
83-
"cf.colo.id",
84-
"ip.src",
85-
"http.request.headers[\"x-api-key\"]"
86-
],
87-
"period": 60,
88-
"requests_per_period": 100,
89-
"mitigation_timeout": 600
90-
}
91-
}'
92-
```
65+
<APIRequest
66+
path="/zones/{zone_id}/rulesets/{ruleset_id}/rules"
67+
method="POST"
68+
json={{
69+
description: "My rate limiting rule",
70+
expression: '(http.request.uri.path matches "^/api/")',
71+
action: "block",
72+
action_parameters: {
73+
response: {
74+
status_code: 403,
75+
content: "You have been rate limited.",
76+
content_type: "text/plain",
77+
},
78+
},
79+
ratelimit: {
80+
characteristics: [
81+
"cf.colo.id",
82+
"ip.src",
83+
'http.request.headers["x-api-key"]',
84+
],
85+
period: 60,
86+
requests_per_period: 100,
87+
mitigation_timeout: 600,
88+
},
89+
}}
90+
/>
9391

9492
<Render file="api-create-ruleset-with-rule" />
9593

9694
### Example C - Rate limiting ignoring cached assets
9795

98-
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `{zone_id}`. The phase entry point ruleset already exists, with ID `{ruleset_id}`.
99-
100-
The new rule does not consider requests for cached assets when calculating the rate.
101-
102-
```bash null {17}
103-
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
104-
--header "Authorization: Bearer <API_TOKEN>" \
105-
--header "Content-Type: application/json" \
106-
--data '{
107-
"description": "My rate limiting rule",
108-
"expression": "(http.request.uri.path matches \"^/api/\")",
109-
"action": "block",
110-
"ratelimit": {
111-
"characteristics": [
112-
"cf.colo.id",
113-
"ip.src",
114-
"http.request.headers[\"x-api-key\"]"
115-
],
116-
"period": 60,
117-
"requests_per_period": 100,
118-
"mitigation_timeout": 600,
119-
"requests_to_origin": true
120-
}
121-
}'
122-
```
96+
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `$ZONE_ID`. The phase entry point ruleset already exists, with ID `$RULESET_ID`.
97+
98+
The new rule does not consider requests for cached assets when calculating the rate (`"requests_to_origin": true`).
99+
100+
<APIRequest
101+
path="/zones/{zone_id}/rulesets/{ruleset_id}/rules"
102+
method="POST"
103+
json={{
104+
description: "My rate limiting rule",
105+
expression: '(http.request.uri.path matches "^/api/")',
106+
action: "block",
107+
ratelimit: {
108+
characteristics: [
109+
"cf.colo.id",
110+
"ip.src",
111+
'http.request.headers["x-api-key"]',
112+
],
113+
period: 60,
114+
requests_per_period: 100,
115+
mitigation_timeout: 600,
116+
requests_to_origin: true,
117+
},
118+
}}
119+
/>
123120

124121
<Render file="api-create-ruleset-with-rule" />
125122

126123
### Example D - Complexity-based rate limiting rule
127124

128125
:::note
129-
130126
[Complexity-based rate limiting](/waf/rate-limiting-rules/request-rate/#complexity-based-rate-limiting) is available in beta and can only be configured via API.
131127
:::
132128

133-
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `{zone_id}`. The phase entry point ruleset already exists, with ID `{ruleset_id}`.
134-
135-
The new rule is a complexity-based rate limiting rule that takes the `my-score` HTTP response header into account to calculate a total complexity score for the client. The counter with the total score is updated when there is a match for the rate limiting rule's counting expression (in this case, the same as the rule expression). When this total score becomes larger than `400` during a 60-second period, any later client requests will be blocked for a period of 600 seconds (10 minutes).
136-
137-
```bash null {14-15}
138-
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
139-
--header "Authorization: Bearer <API_TOKEN>" \
140-
--header "Content-Type: application/json" \
141-
--data '{
142-
"description": "My complexity-based rate limiting rule",
143-
"expression": "http.request.uri.path matches \"^/graphql/\"",
144-
"action": "block",
145-
"ratelimit": {
146-
"characteristics": [
147-
"cf.colo.id",
148-
"http.request.headers[\"x-api-key\"]"
149-
],
150-
"period": 60,
151-
"score_per_period": 400,
152-
"score_response_header_name": "my-score",
153-
"mitigation_timeout": 600,
154-
"counting_expression": ""
155-
}
156-
}'
157-
```
129+
This example adds a rate limiting rule to the `http_ratelimit` phase entry point ruleset for the zone with ID `$ZONE_ID`. The phase entry point ruleset already exists, with ID `$RULESET_ID`.
130+
131+
The new rule is a complexity-based rate limiting rule that takes the `my-score` HTTP response header into account to calculate a total complexity score for the client. The counter with the total score is updated when there is a match for the rate limiting rule's counting expression (in this case, the same as the rule expression since `counting_expression` is an empty string). When this total score becomes larger than `400` during a period of `60` seconds, any later client requests will be blocked for a period of `600` seconds (10 minutes).
132+
133+
<APIRequest
134+
path="/zones/{zone_id}/rulesets/{ruleset_id}/rules"
135+
method="POST"
136+
json={{
137+
description: "My complexity-based rate limiting rule",
138+
expression: 'http.request.uri.path matches "^/graphql/"',
139+
action: "block",
140+
ratelimit: {
141+
characteristics: ["cf.colo.id", 'http.request.headers["x-api-key"]'],
142+
score_response_header_name: "my-score",
143+
score_per_period: 400,
144+
period: 60,
145+
mitigation_timeout: 600,
146+
counting_expression: "",
147+
},
148+
}}
149+
/>
158150

159151
<Render file="api-create-ruleset-with-rule" />
160152

0 commit comments

Comments
 (0)