Skip to content

Commit 54a8f45

Browse files
aaron-ruby-dfaaron-ruby-df
authored
Bugfix/pcx 1036 firewall fix migration issues (#211)
* PCX-1036 Fix Firewall Rules migration bugs * PCX-1036 Restore package.json * PCX-1036 QA copy pass Co-authored-by: Aaron Ruby <[email protected]>
1 parent 3617ce6 commit 54a8f45

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+979
-1264
lines changed

‎products/firewall/src/content/api/cf-filters/endpoints.md‎

Lines changed: 56 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,24 @@
11
---
2-
title: Endpoints
2+
type: table
33
order: 455
44
---
55

66
# Endpoints
77

8+
<ContentColumn>
9+
810
To invoke a Cloudflare Filters API operation, append the endpoint to the Cloudflare API base URL:
911

10-
`https://api.cloudflare.com/client/v4/`
12+
```html
13+
14+
https://api.cloudflare.com/client/v4/
15+
```
1116

1217
For authentication instructions, see [_Getting Started: Requests_](https://api.cloudflare.com/#getting-started-requests) in the Cloudflare API documentation.
1318

1419
For help with endpoints and pagination, see [_Getting Started: Endpoints_](https://api.cloudflare.com/#getting-started-endpoints).
1520

16-
<Aside type='warning'>
21+
<Aside type='warning' header='Important'>
1722

1823
The Filters API endpoints require a value for _{zone_id}_.
1924

@@ -23,52 +28,54 @@ To retrieve a list of zones associated with your account, use the [List Zones](h
2328

2429
The Cloudflare Filters API supports the operations outlined below. Visit the associated links for examples.
2530

26-
<TableWrap>
27-
<table style="width: 100%;">
28-
<thead>
31+
</ContentColumn>
32+
33+
<TableWrap style='width:100%'>
34+
<table style='table-layout:fixed; width:100%'>
35+
<thead>
36+
<tr>
37+
<th>Operation</th>
38+
<th>Method & Endpoint</th>
39+
<th>Notes</th>
40+
</tr>
41+
</thead>
42+
<tbody>
43+
<tr>
44+
<td><a href='/api/cf-filters/post/'>Create filters</a></td>
45+
<td><code class="InlineCode">POST zones/{'{zone_id}'}/filters</code></td>
46+
<td>Handled as a single transaction. If there is an error, the entire operation fails.</td>
47+
</tr>
48+
<tr>
49+
<td><a href='/api/cf-filters/get/#get-all-filters'>Fetch all filters</a></td>
50+
<td><code class="InlineCode">GET zones/{'{zone_id}'}/filters</code></td>
51+
<td>Lists all current filters. Results return paginated with 25 items per page by default. Use optional parameters to narrow results.</td>
52+
</tr>
53+
<tr>
54+
<td><a href='/api/cf-filters/get/#get-by-filter-id'>Fetch a filter by ID</a></td>
55+
<td><code class="InlineCode">GET zones/{'{zone_id}'}/filters/{'{id}'}</code></td>
56+
<td>Retrieve a single filter by ID.</td>
57+
</tr>
58+
<tr>
59+
<td><a href='/api/cf-filters/put/#update-multiple-filters'>Update multiple filters</a></td>
60+
<td><code class="InlineCode">PUT zones/{'{zone_id}'}/filters</code></td>
61+
<td>Handled as a single transaction. All filters must exist for operation to succeed. If there is an error, the entire operation fails.</td>
62+
</tr>
63+
<tr>
64+
<td><a href='/api/cf-filters/put/#update-a-single-filter'>Update a single filter by ID</a></td>
65+
<td><code class="InlineCode">PUT zones/{'{zone_id}'}/filters/{'{id}'}</code></td>
66+
<td>Update a single filter by ID.</td>
67+
</tr>
68+
<tr>
69+
<td><a href='/api/cf-filters/delete/#delete-multiple-filters'>Delete multiple filters</a></td>
70+
<td><code class="InlineCode">DELETE zones/{'{zone_id}'}/filters</code></td>
71+
<td><p>Delete existing filters. Must specify list of filter IDs.</p>
72+
<p>Empty requests result in no deletion. Returns HTTP status code 200 if a specified filter does not exist.</p></td>
73+
</tr>
2974
<tr>
30-
<th>Operation</th>
31-
<th>Method & Endpoint</th>
32-
<th>Notes</th>
75+
<td><a href='/api/cf-filters/delete/#delete-a-single-filter'>Delete a single filter by ID</a></td>
76+
<td><code class="InlineCode">DELETE zones/{'{zone_id}'}/filters/{'{id}'}</code></td>
77+
<td>Delete a filter by ID.</td>
3378
</tr>
34-
</thead>
35-
<tbody>
36-
<tr>
37-
<td><a href='/firewall/api/cf-filters/post/'>Create filters</a></td>
38-
<td><code class="InlineCode">POST&nbsp;zones/{'{zone_id}'}/filters</code></td>
39-
<td>Handled as a single transaction. If there is an error, the entire operation fails.</td>
40-
</tr>
41-
<tr>
42-
<td><a href='/firewall/api/cf-filters/get/#get-all-filters'>Fetch all filters</a></td>
43-
<td><code class="InlineCode">GET&nbsp;zones/{'{zone_id}'}/filters</code></td>
44-
<td>Lists all current filters. Results return paginated with 25 items per page by default. Use optional parameters to narrow results.</td>
45-
</tr>
46-
<tr>
47-
<td><a href='/firewall/api/cf-filters/get/#get-by-filter-id'>Fetch a filter by ID</a></td>
48-
<td><code class="InlineCode">GET&nbsp;zones/{'{zone_id}'}/filters/{'{id}'}</code></td>
49-
<td>Retrieve a single filter by ID.</td>
50-
</tr>
51-
<tr>
52-
<td><a href='/firewall/api/cf-filters/put/#update-multiple-filters'>Update multiple filters</a></td>
53-
<td><code class="InlineCode">PUT&nbsp;zones/{'{zone_id}'}/filters</code></td>
54-
<td>Handled as a single transaction. All filters must exist for operation to succeed. If there is an error, the entire operation fails.</td>
55-
</tr>
56-
<tr>
57-
<td><a href='/firewall/api/cf-filters/put/#update-a-single-filter'>Update a single filter by ID</a></td>
58-
<td><code class="InlineCode">PUT&nbsp;zones/{'{zone_id}'}/filters/{'{id}'}</code></td>
59-
<td>Update a single filter by ID.</td>
60-
</tr>
61-
<tr>
62-
<td><a href='/firewall/api/cf-filters/delete/#delete-multiple-filters'>Delete multiple filters</a></td>
63-
<td><code class="InlineCode">DELETE&nbsp;zones/{'{zone_id}'}/filters</code></td>
64-
<td><p>Delete existing filters. Must specify list of filter IDs.</p>
65-
<p>Empty requests result in no deletion. Returns HTTP status code 200 if a specified filter does not exist.</p></td>
66-
</tr>
67-
<tr>
68-
<td><a href='/firewall/api/cf-filters/delete/#delete-a-single-filter'>Delete a single filter by ID</a></td>
69-
<td><code class="InlineCode">DELETE&nbsp;zones/{'{zone_id}'}/filters/{'{id}'}</code></td>
70-
<td>Delete a filter by ID.</td>
71-
</tr>
72-
</tbody>
73-
</table>
79+
</tbody>
80+
</table>
7481
</TableWrap>

‎products/firewall/src/content/api/cf-filters/index.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,7 @@ For example, a filter matching:
1414

1515
may be associated with a firewall rule declaring that the request should be blocked.
1616

17-
<Aside type="note">
18-
19-
Currently, Cloudflare Filters in an API-only feature and lacks a graphical user interface.
20-
21-
</Aside>
17+
Use Rules Lists within a filter to refer collectively to a group of IP addresses. Refer to the [Rules List API](/api/cf-lists/) for more information.
2218

2319
Before getting started with the Cloudflare Filters API, familiarize yourself with Firewall Rules [expressions](/cf-firewall-rules/fields-and-expressions/). For a complete reference, see [_Firewall Rules language_](/cf-firewall-language).
2420

@@ -29,6 +25,4 @@ The Firewall Rules API behaves differently from most Cloudflare APIs in two ways
2925
- API calls accept and return multiple items, and allow applying data changes to multiple items.
3026
- Although API calls return the [standard response](https://api.cloudflare.com/#getting-started-responses), the error object follows the [JSON API standard](http://jsonapi.org/format/#errors), such that in an error condition, it is clear which item produced the error and why.
3127

32-
## Get started!
33-
3428
To get started, review [What is a filter?](/api/cf-filters/what-is-a-filter/), followed by the Cloudflare Filters [JSON object](/api/cf-firewall-rules/json-object/) and [Endpoints](/api/cf-firewall-rules/endpoints/).

‎products/firewall/src/content/api/cf-filters/json-object.md‎

Lines changed: 26 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
---
2-
title: JSON object
32
order: 450
43
---
54

65
# JSON object
76

87
## Filters object structure and properties
98

10-
A filter JSON object has the following structure:
9+
A JSON response for the [Filters API](https://api.cloudflare.com/#filters-properties) has this structure:
1110

1211
```json
1312
{
@@ -19,62 +18,46 @@ A filter JSON object has the following structure:
1918
}
2019
```
2120

22-
The table below summarizes the JSON object properties.
21+
This table summarizes the object properties:
2322

2423
<TableWrap>
25-
<table style="width: 100%;">
24+
<table style="table-layout:fixed; width: 100%;">
2625
<thead>
2726
<tr>
2827
<th>Property</th>
29-
<th style="width:30%">Description</th>
30-
<th style="width:30%">Value</th>
31-
<th>Notes</th>
28+
<th>Description</th>
29+
<th>Constraints</th>
3230
</tr>
3331
</thead>
3432
<tbody>
33+
<tr>
34+
<td><code>id</code><br /><Type>String</Type></td>
35+
<td>A UUIDv4 identifier generated by Cloudflare.</td>
36+
<td>
37+
<p>Unique, read only</p>
38+
<p>Length: 32 characters</p>
39+
</td>
40+
</tr>
3541
<tr>
36-
<td>id</td>
37-
<td>- ID generated by Cloudflare</td>
38-
<td>32-char UUIDv4 identifier</td>
39-
<td>
40-
- Unique
41-
<br/> - Read-only
42-
</td>
42+
<td><code>expression</code><br /><Type>String</Type></td>
43+
<td>A Firewall Rules expression used to evaluate requests. For more, see <a href="/firewall/cf-firewall-rules/fields-and-expressions/#expressions"><em>Expressions</em></a>.
44+
</td>
45+
<td></td>
4346
</tr>
4447
<tr>
45-
<td>expression</td>
46-
<td>- A filter expression</td>
47-
<td><em>See <a href="/firewall/cf-firewall-rules/fields-and-expressions/#expressions">expressions</a></em></td>
48-
<td>- Required
49-
<br/> - Double quotes are escaped because of the double quoted JSON value</td>
48+
<td><code>paused</code><br /><Type>Boolean</Type></td>
49+
<td>Returns <code class='InlineCode'>true</code> when the filter is not active. Use <code>ref</code> to enable/disable the filter.</td>
50+
<td>Default: <code class='InlineCode'>false</code></td>
5051
</tr>
5152
<tr>
52-
<td>paused</td>
53-
<td>- Indicates if the filter is active</td>
54-
<td>
55-
<p><em>true</em></p>
56-
<p><em>false</em></p>
57-
</td>
58-
<td>- Optional
59-
<br/> - Default is <em>false</em></td>
53+
<td><code>description</code><br /><Type>String</Type></td>
54+
<td>An informative summary of the filter.</td>
55+
<td>Maximum length: 500 characters</td>
6056
</tr>
6157
<tr>
62-
<td>description</td>
63-
<td>
64-
- To briefly describe the filter
65-
<br/> - Omitted from object if empty
66-
</td>
67-
<td>text</td>
68-
<td>
69-
<p>- Optional
70-
<br/> - Default is empty</p>
71-
</td>
72-
</tr>
73-
<tr>
74-
<td>ref</td>
75-
<td>- Unique, user-supplied identifier or reference</td>
76-
<td>At user's discretion</td>
77-
<td>- Useful for identifying a filter if Cloudflare ID is unknown</td>
58+
<td><code>ref</code><br /><Type>String</Type></td>
59+
<td>A short string for tagging filters.</td>
60+
<td>Maximum length: 50 characters</td>
7861
</tr>
7962
</tbody>
8063
</table>

‎products/firewall/src/content/api/cf-filters/validation.md‎

Lines changed: 18 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Expression validation
32
order: 480
3+
type: table
44
---
55

66
# Expression validation
@@ -11,45 +11,43 @@ The Cloudflare Filters API supports an endpoint for validating expressions.
1111
<table style="width: 100%;">
1212
<thead>
1313
<tr>
14-
<th style="width:30%;">
15-
Method + URL
14+
<th>
15+
Operation
1616
</th>
1717
<th>
18-
Description
18+
Method + Endpoint
1919
</th>
20-
<th style="width:40%;">
20+
<th>
2121
Notes
2222
</th>
2323
</tr>
2424
</thead>
2525
<tbody>
2626
<tr>
27-
<td>GET https://api.cloudflare.com/client/v4/filters/validate-expr</td>
28-
<td>Validate via a query string (<em>?expression=</em>) </td>
27+
<td style='width:25%; word-wrap:break-word; white-space:normal'>Validate expression via query string (<em>?expression=</em>) </td>
28+
<td><code class='InlineCode'>GET /filters/validate-expr</code></td>
2929
<td>Allows testing and validating expressions without changing anything</td>
3030
</tr>
3131
<tr>
32-
<td>POST https://api.cloudflare.com/client/v4/filters/validate-expr</td>
33-
<td>Validate via a JSON object</td>
32+
<td style='width:25%; word-wrap:break-word; white-space:normal'>Validate expression via JSON object</td>
33+
<td><code class='InlineCode'>POST /filters/validate-expr</code></td>
3434
<td>Allows testing and validating expressions without changing anything</td>
3535
</tr>
3636
</tbody>
3737
</table>
3838
</TableWrap>
3939

40-
## Example calls
40+
## Examples
4141

42-
```bash
43-
GET /filters/validate-expr
44-
```
42+
### Validate expression via query string
4543

46-
### Request
44+
#### Request
4745

4846
```bash
4947
curl -X GET -H "X-Auth-Email: [email protected]" -H "X-Auth-Key: REDACTED" 'https://api.cloudflare.com/client/v4/filters/validate-expr?expression=ip.src==34'
5048
```
5149

52-
### Response
50+
#### Response
5351

5452
```json
5553
{
@@ -64,21 +62,17 @@ curl -X GET -H "X-Auth-Email: [email protected]" -H "X-Auth-Key: REDACTED" 'ht
6462
}
6563
```
6664

67-
Note that the error message when rendered in fixed width font lines up with the position of the error in the input and the text describes the error:
65+
Note the validation error in the response. In this example, the error is due to an invalid IP address format:
6866

6967
```bash
7068
Filter parsing error:
7169
`ip.src==34`
7270
^^ couldn't parse address in network: invalid IP address syntax
7371
```
7472
75-
Which is correct as `34` is not an IP address.
73+
### Validate expression via JSON object
7674
77-
```bash
78-
POST /filters/validate-expr
79-
```
80-
81-
### Request
75+
#### Request
8276
8377
```bash
8478
curl -X POST \
@@ -90,7 +84,7 @@ curl -X POST \
9084
}' "https://api.cloudflare.com/client/v4/filters/validate-expr"
9185
```
9286
93-
### Response
87+
#### Response
9488
9589
```json
9690
{
@@ -105,12 +99,10 @@ curl -X POST \
10599
}
106100
```
107101
108-
Which is:
102+
Note the validation error in the response. In this example, the value for the subnet mask, `/2000`, is not a valid IPv6 CIDR mask:
109103
110104
```bash
111105
Filter parsing error:
112106
`ip.src in {2400:cb00::/32 2405:8100::/2000 2405:b500::/32 2606:4700::/32 2803:f800::/32 2c0f:f248::/32 2a06:98c0::/29}`
113107
^^^^ number too large to fit in target type while parsing with radix 10
114108
```
115-
116-
Which is correct, as `/2000` is not a valid mask for an IPv6 CIDR.

‎products/firewall/src/content/api/cf-firewall-rules/delete.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,11 @@ curl -X DELETE \
2323
"https://api.cloudflare.com/client/v4/zones/d56084adb405e0b7e32c52321bf07be6/firewall/rules?id=cbf4b7a5a2a24e59a03044d6d44ceb09"
2424
```
2525

26-
**Important note**: `DELETE` does not delete any filter related to the firewall rule. To delete the filter, it's necessary to call the `/filters` API.
26+
<Aside type='note' header='Note'>
27+
28+
`DELETE` does not delete any filter related to the firewall rule. To delete the filter, it's necessary to call the `/filters` API.
29+
30+
</Aside>
2731

2832
### Response
2933

0 commit comments

Comments
 (0)