Skip to content

Commit 719f883

Browse files
nikitacanopedrosousa
authored and
maheshwarip
committed
[Snippets] API + Phases documentation (#16886)
--------- Co-authored-by: Pedro Sousa <[email protected]>
1 parent 7884e59 commit 719f883

File tree

10 files changed

+145
-40
lines changed

10 files changed

+145
-40
lines changed

‎src/content/docs/rules/cloud-connector/create-api.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ The following table summarizes the available operations.
3434

3535
| Operation | Verb + Endpoint |
3636
| ------------------------------------------ | -------------------------------------------- |
37-
| List Cloud Connector rules | `GET zones/{zone_id}/cloud_connector/rules` |
37+
| List Cloud Connector rules | `GET /zones/{zone_id}/cloud_connector/rules` |
3838
| Create/update/delete Cloud Connector rules | `PUT /zones/{zone_id}/cloud_connector/rules` |
3939

4040
## Example API calls
@@ -70,6 +70,10 @@ curl https://api.cloudflare.com/client/v4/zones/{zone_id}/cloud_connector/rules
7070

7171
### Create/update/delete Cloud Connector rules
7272

73+
:::caution
74+
To create a new rule and keep all existing rules, you must include them all in your request body. Omitting an existing rule in the request body will delete the corresponding Cloud Connector rule.
75+
:::
76+
7377
The following example request will replace all existing Cloud Connector rules with a single rule:
7478

7579
```bash
@@ -92,7 +96,3 @@ curl --request PUT \
9296
The required body parameters for each rule are: `expression`, `provider`, and `parameters.host`.
9397

9498
The `provider` value must be one of the following: `aws_s3`, `azure_storage`, and `gcp_storage`.
95-
96-
:::caution
97-
To create a new rule and keep all existing rules, you must include them all in your request body. Omitting an existing rule in the request body will delete the corresponding Cloud Connector rule.
98-
:::

‎src/content/docs/rules/custom-error-responses/create-api.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ head:
88
content: Create a custom error response via API
99
---
1010

11-
Configure custom error responses as [rules](/ruleset-engine/about/rules/) belonging to the `http_custom_errors` phase. Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create custom error responses via API.
11+
Configure Custom Error Responses as [rules](/ruleset-engine/about/rules/) belonging to the `http_custom_errors` phase. Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create Custom Error Responses via API.
1212

1313
## Basic rule settings
1414

@@ -121,6 +121,6 @@ This `PUT` request, corresponding to the [Update a zone entry point ruleset](/ap
121121

122122
## ​​Required API token permissions
123123

124-
The API token used in API requests to manage custom error responses must have at least the following permission:
124+
The API token used in API requests to manage Custom Error Responses must have at least the following permission:
125125

126126
- _Custom Error Rules_ > _Edit_

‎src/content/docs/rules/custom-error-responses/index.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,24 @@
11
---
22
pcx_content_type: concept
3-
title: Custom error responses
3+
title: Custom Error Responses
44
sidebar:
55
order: 12
66
badge:
77
text: Beta
88
head:
99
- tag: title
10-
content: Custom error responses
10+
content: Custom Error Responses
1111

1212
---
1313

14-
Custom error responses, powered by the [Ruleset Engine](/ruleset-engine/), allow you to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). Custom error responses will apply to responses whose HTTP status code is greater than or equal to 400 that match the expression of the custom error response rule.
14+
Custom Error Responses, powered by the [Ruleset Engine](/ruleset-engine/), allow you to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). Custom Error Responses will apply to responses whose HTTP status code is greater than or equal to 400 that match the expression of the custom error response rule.
1515

1616
To configure a custom error response, create a custom error response rule at the zone level. Custom error response rules will override [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/) at the zone or account level.
1717

1818
:::note[Notes about the beta]
1919

2020

21-
During the beta, you can define custom error responses using inline templates and specify the response's content type and HTTP status code.
21+
During the beta, you can define Custom Error Responses using inline templates and specify the response's content type and HTTP status code.
2222

2323
Additionally, at this stage you can only create custom error response rules [using the API](/rules/custom-error-responses/create-api/).
2424

@@ -33,12 +33,12 @@ Additionally, you can configure [HTTP response header modification rules](/rules
3333

3434
## Availability
3535

36-
Custom error responses are available in beta to all paid plans. The exact features depend on your Cloudflare plan:
36+
Custom Error Responses are available in beta to all paid plans. The exact features depend on your Cloudflare plan:
3737

3838

3939

4040
| | Free | Pro | Business | Enterprise |
4141
| ------------------------------------- | :--: | :-: | :------: | :--------: |
42-
| Custom error responses | No | Yes | Yes | Yes |
42+
| Custom Error Responses | No | Yes | Yes | Yes |
4343
| Number of custom error response rules | — | 5 | 20 | 50 |
4444
| | | | | |

‎src/content/docs/rules/custom-error-responses/parameters.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ head:
99

1010
---
1111

12-
Custom error responses have the following parameters:
12+
Custom Error Responses have the following parameters:
1313

1414

1515

‎src/content/docs/rules/index.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,9 +69,9 @@ Rules features require that you [proxy the DNS records](/dns/manage-dns-records/
6969
</Feature>
7070

7171
<Feature
72-
header="Custom error responses"
72+
header="Custom Error Responses"
7373
href="/rules/custom-error-responses/"
74-
cta="Configure custom error responses"
74+
cta="Configure Custom Error Responses"
7575
>
7676
Define custom responses for errors returned by an origin server or by a
7777
Cloudflare product, including Workers.

‎src/content/docs/rules/reference/esc-deprecation.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ The following table contains recommendations for different use cases of ESC:
3131
| Rewrite URI | Request a different URL from the origin server while displaying the original request URL in the visitor's browser. | Use [Transform Rules](/rules/transform/url-rewrite/) to rewrite URLs. |
3232
| Set/clear request headers | Set (or clear) HTTP headers sent to the origin server. | Use [Transform Rules](/rules/transform/request-header-modification/) to modify request headers. |
3333
| Feature exceptions | Exclude specific requests from one or more Cloudflare security products. | Use [Configuration Rules](/rules/configuration-rules/settings/). |
34-
| Send custom error response | Abort the current request, returning a specific response body and/or HTTP status code to the client. | Use [custom error responses](/rules/custom-error-responses/) to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). |
34+
| Send custom error response | Abort the current request, returning a specific response body and/or HTTP status code to the client. | Use [Custom Error Responses](/rules/custom-error-responses/) to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). |
3535
| Set/add/remove response headers | Update, add, or remove headers from the response returned by the origin server. | Use [Transform Rules](/rules/transform/response-header-modification/) to modify response headers. |
3636
| Status redirect | After receiving a response from the origin, conditionally send a redirect back to the client if the origin response code matches a key in the supplied table. | Use [Cloudflare Workers](/workers/). Refer to the [Modify response](/workers/examples/modify-response/) example for a similar use case. |
3737
| Add cookies to response | Set cookies in the response sent to the client. | Use [Transform Rules](/rules/transform/response-header-modification/) to modify response headers (which includes setting cookies). |

‎src/content/docs/rules/snippets/create-api.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Configure via API
3+
pcx_content_type: how-to
4+
sidebar:
5+
order: 3
6+
head:
7+
- tag: title
8+
content: Configure Snippets via API
9+
---
10+
11+
You can create Snippets using the [Cloudflare API](/fundamentals/api/).
12+
13+
## Required permissions
14+
15+
The [API token](/fundamentals/api/get-started/create-token/) used in API requests to manage Snippets must have at least the following permission:
16+
17+
- _Zone_ > _Snippets_ > _Edit_
18+
19+
:::note
20+
A token with this permission is only valid for the Snippets endpoints described in this page. You cannot use it to interact with the `http_request_snippets` phase via [Rulesets API](/ruleset-engine/rulesets-api/).
21+
:::
22+
23+
## Endpoints
24+
25+
To obtain the complete endpoint, append the Snippets endpoints listed below to the Cloudflare API base URL:
26+
27+
```txt
28+
https://api.cloudflare.com/client/v4
29+
```
30+
31+
The `{zone_id}` argument is the [zone ID](/fundamentals/setup/find-account-and-zone-ids/) (a hexadecimal string). You can find this value in the Cloudflare dashboard.
32+
33+
The following table summarizes the available operations.
34+
35+
| Operation | Verb + Endpoint |
36+
| ------------------------------------------ | ------------------------------------------------------ |
37+
| List all code snippets | `GET /zones/{zone_id}/snippets` |
38+
| Create/update code snippet | `PUT /zones/{zone_id}/snippets/{snippet_name}` |
39+
| Delete code snippet | `DELETE /zones/{zone_id}/snippets/{snippet_name}` |
40+
| List snippet rules | `GET /zones/{zone_id}/snippets/snippet_rules` |
41+
| Create/update/delete snippet rules | `PUT /zones/{zone_id}/snippets/snippet_rules` |
42+
43+
## Example API calls
44+
45+
### Create/update code snippet
46+
47+
To create or update a Snippet, use the following `PUT` request. The snippet is named `{snippet_name}` and the body contains the JavaScript code.
48+
49+
```bash
50+
curl --request PUT https://api.cloudflare.com/client/v4/zones/{zone_id}/snippets/{snippet_name} \
51+
--header "Authorization: Bearer <API_TOKEN>" \
52+
--header "Content-Type: multipart/form-data" \
53+
--form [email protected] \
54+
--form metadata='{"main_module":"example.js"}'
55+
```
56+
57+
The required body parameters are:
58+
59+
- `files`: The file with your JavaScript code.
60+
- `metadata`: Object containing `main_module`, which must match the filename of the uploaded file.
61+
62+
To make this example work, save your JavaScript code in a file named `example.js`, and then execute `curl` command with a `PUT` request from the folder where `example.js` is located.
63+
64+
```json title="Example response"
65+
{
66+
"errors": [],
67+
"messages": [],
68+
"success": true,
69+
"result": {
70+
"created_on": "2023-07-24-00:00:00",
71+
"modified_on": "2023-07-24-00:00:00",
72+
"snippet_name": "snippet_name_01"
73+
}
74+
}
75+
```
76+
77+
### Create/update/delete snippet rules
78+
79+
:::caution
80+
When using this endpoint to create a new rule and keep existing rules, you must include all rules in the request body. Omitting an existing rule will delete the corresponding rule.
81+
:::
82+
83+
Once you have created a code snippet, you can link it to rules. This is done via the following `PUT` request to the `snippet_rules` endpoint.
84+
85+
```bash
86+
curl --request PUT \
87+
"https://api.cloudflare.com/client/v4/zones/{zone_id}/snippets/snippet_rules" \
88+
--header "Authorization: Bearer <API_TOKEN>" \
89+
--header "Content-Type: application/json" \
90+
--data '{
91+
"rules": [
92+
{
93+
"description": "Trigger snippet on specific cookie",
94+
"enabled": true,
95+
"expression": "http.cookie eq \"a=b\"",
96+
"snippet_name": "snippet_name_01"
97+
}
98+
]
99+
}'
100+
```

‎src/content/docs/rules/snippets/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ For code samples addressing common use cases, please refer to the [Examples](/ru
2020

2121
To create and deploy a Snippet, you need to define the following elements:
2222

23-
- **Snippet**: JavaScript code to be executed during the request-handling process.
23+
- **Code snippet**: JavaScript code to be executed during the request-handling process.
2424
- **Snippet rule**: A [filter expression](/ruleset-engine/rules-language/expressions/) that determines which requests the Snippet will be applied to. Each Snippet can only be associated with one Snippet Rule.
2525

2626
For more information, refer to the [How it works](/rules/snippets/how-it-works/) and [Create in the dashboard](/rules/snippets/create-dashboard/) sections.

0 commit comments

Comments
 (0)