Skip to content

Integrating with GraphQL API Explorer #22282

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 14, 2025
Merged

Integrating with GraphQL API Explorer #22282

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
de0a450
Integrating with GraphQL API Explorer
cf-ypark May 7, 2025
228d67e
updated CONTRIBUTING.md
cf-ypark May 8, 2025
e56ae23
Apply suggestions from code review
cf-ypark May 8, 2025
7acf5fc
Merge branch 'production' into young/graphql-api-explorer
cf-ypark May 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,3 +99,69 @@ export default {
would render as

<img width="870" alt="Screenshot 2024-02-20 at 14 29 22" src="https://github.com/cloudflare/cloudflare-docs/assets/28503158/56aa8016-b3b6-4d64-8213-b1a26f16534a">

## GraphQL API Explorer

If you are adding a code snippet to the documentation that is an executable GraphQL query, you can add `graphql-api-explorer` right after `graphql` in the code block metadata (both must be present). This will render a button that allows users to open the query in the [GraphQL API Explorer](https://graphql.cloudflare.com/explorer). For example:

````
```graphql graphql-api-explorer title="A GraphQL query"
query GraphqlExample($zoneTag: string, $start: Time, $end: Time) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
firewallEventsAdaptive(
filter: { datetime_gt: $start, datetime_lt: $end }
limit: 2
orderBy: [datetime_DESC]
) {
action
datetime
host: clientRequestHTTPHost
}
}
}
}
```
````

When the `Run in GraphQL API Explorer` button is clicked, the following variables will be pre-populated in the GraphQL API Explorer along with the query.

**Note: The user must be logged in or have an API token saved to see the query and variables pre-populated.**

```
{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z"}
```

### Conventions to auto populate `Variables` section in the GraphQL API Explorer

By default, the `Variables` section will be automatically populated based on the variables used in the GraphQL query.

- Any variable name that includes `start` and has a type of `Time` --> start: "2025-05-09T14:58:06Z" (6 hours from the current time)
- e.g. `datetimeStart` also has `start` keyword, so it will be recognized for a start time (or date)
- Any variable name that includes `end` and has a type of `Time` --> end: "2025-05-09T20:58:06Z" (current time)
- Any variable name that includes `start` and has a type of `Date` --> start: "2025-05-07" (24 hours from the current date)
- Any variable name that includes `end` and has a type of `Date` --> end: "2025-05-08" (current date)
- `zoneTag` and has a type of `string` --> zoneTag: "ZONE_ID"
- `accountTag` and has a type of `string` --> accountTag: "<ACCOUNT_ID>"
- Any variable name that includes `id` and has a type of `string` --> id: "<REPLACE_WITH_ID>"
- Any variable name and has a type of string --> anyString: "<REPLACE_WITH_STRING>"
- `limit` with type `*int*` --> limit: 100

In addition to the variables that are automatically populated, you can add custom variables by setting their values as a JSON string in the `graphql-api-explorer` metadata.

````
```graphql graphql-api-explorer='{"uID": "something"}' title="A GraphQL query"
query GraphqlExample($zoneTag: string, $start: Time, $end: Time) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
...
}
}
}
````

The variables added via the metadata value will be merged with the automatically populated variables.

```
{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z", "uId": "something"}
```
2 changes: 2 additions & 0 deletions ec.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import lightTheme from "solarflare-theme/themes/cloudflare-light-color-theme.jso
import pluginWorkersPlayground from "./src/plugins/expressive-code/workers-playground.js";
import pluginOutputFrame from "./src/plugins/expressive-code/output-frame.js";
import pluginDefaultTitles from "./src/plugins/expressive-code/default-titles.js";
import pluginGraphqlApiExplorer from "./src/plugins/expressive-code/graphql-api-explorer.js";

import { pluginCollapsibleSections } from "@expressive-code/plugin-collapsible-sections";

Expand All @@ -16,6 +17,7 @@ export default defineEcConfig({
pluginOutputFrame(),
pluginDefaultTitles(),
pluginCollapsibleSections(),
pluginGraphqlApiExplorer(),
],
themes: [darkTheme, lightTheme],
styleOverrides: {
Expand Down
174 changes: 89 additions & 85 deletions src/content/docs/analytics/graphql-api/features/discovery/introspection.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ pcx_content_type: reference
title: Introspection
sidebar:
order: 41

---

Cloudflare GraphQL API has a dynamic schema and exposes more than 70 datasets
Expand Down Expand Up @@ -50,104 +49,109 @@ etc).
Alternatively, you can also do it manually by using `__schema` node with the
needed directives.

```graphql title="A typical introspection query"
```graphql graphql-api-explorer title="A typical introspection query"
{
__schema {
queryType { name }
mutationType { name }
subscriptionType { name }
types {
...FullType
}
directives {
name
description
locations
args {
...InputValue
}
}
}
__schema {
queryType {
name
}
mutationType {
name
}
subscriptionType {
name
}
types {
...FullType
}
directives {
name
description
locations
args {
...InputValue
}
}
}
}
fragment TypeRef on __Type {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
}
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
}
}
fragment InputValue on __InputValue {
name
description
type { ...TypeRef }
defaultValue
name
description
type {
...TypeRef
}
defaultValue
}
fragment FullType on __Type {
kind
name
description
fields(includeDeprecated: true) {
name
description
args {
...InputValue
}
type {
...TypeRef
}
isDeprecated
deprecationReason
}
inputFields {
...InputValue
}
interfaces {
...TypeRef
}
enumValues(includeDeprecated: true) {
name
description
isDeprecated
deprecationReason
}
possibleTypes {
...TypeRef
}
kind
name
description
fields(includeDeprecated: true) {
name
description
args {
...InputValue
}
type {
...TypeRef
}
isDeprecated
deprecationReason
}
inputFields {
...InputValue
}
interfaces {
...TypeRef
}
enumValues(includeDeprecated: true) {
name
description
isDeprecated
deprecationReason
}
possibleTypes {
...TypeRef
}
}
```

For more details on how to send a GraphQL request with curl, please refer to
[this guide][4].

[1]: https://graphql.org/learn/introspection/

[2]: /analytics/graphql-api/features/discovery/settings/

[3]: /analytics/graphql-api/getting-started/explore-graphql-schema/

[4]: /analytics/graphql-api/getting-started/execute-graphql-query/
81 changes: 39 additions & 42 deletions src/content/docs/analytics/graphql-api/features/discovery/settings.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ pcx_content_type: reference
title: Settings node
sidebar:
order: 43

---

Cloudflare GraphQL API exposes more than 70 datasets to its customers. These
Expand Down Expand Up @@ -40,64 +39,62 @@ available for both zones and accounts scopes.

Every subnode of `settings` node could consist of these fields:

* `enabled` - shows whether the node is available for a requester or not;
* `availableFields` - shows the list of fields available for a requester. If
- `enabled` - shows whether the node is available for a requester or not;
- `availableFields` - shows the list of fields available for a requester. If
it's a nested field, the path will be returned, like `sum_requests`;
* `maxPageSize` - retrieves the maximum number of records that can be returned
* `maxNumberOfFields` - answers on how many fields could be used in a single
- `maxPageSize` - retrieves the maximum number of records that can be returned
- `maxNumberOfFields` - answers on how many fields could be used in a single
query for that node;
* `notOlderThan` - returns a number of seconds on how far back in time a query
- `notOlderThan` - returns a number of seconds on how far back in time a query
can read;
* `maxDuration` - shows how wide the requested time range could be.
- `maxDuration` - shows how wide the requested time range could be.

## A sample query

```graphql title="Get boundaries of firewallEventsAdaptive node"
{
viewer {
zones(filter: { zoneTag: $zoneTag }) {
settings {
firewallEventsAdaptive {
enabled
maxDuration
maxNumberOfFields
maxPageSize
notOlderThan
}
}
}
}
```graphql graphql-api-explorer title="Get boundaries of firewallEventsAdaptive node"
query SampleQuery($zoneTag: string) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
settings {
firewallEventsAdaptive {
enabled
maxDuration
maxNumberOfFields
maxPageSize
notOlderThan
}
}
}
}
}
```

```json title="firewallEventsAdaptive limits for a given user"
{
"data": {
"viewer": {
"zones": [
{
"settings": {
"firewallEventsAdaptive": {
"enabled": true,
"maxDuration": 259200,
"maxNumberOfFields": 30,
"maxPageSize": 10000,
"notOlderThan": 2678400
}
}
}
]
}
},
"errors": null
"data": {
"viewer": {
"zones": [
{
"settings": {
"firewallEventsAdaptive": {
"enabled": true,
"maxDuration": 259200,
"maxNumberOfFields": 30,
"maxPageSize": 10000,
"notOlderThan": 2678400
}
}
}
]
}
},
"errors": null
}
```

To get more details on how to execute queries, please refer to our how to get
started [guides][3].

[1]: /analytics/graphql-api/limits/

[2]: /analytics/graphql-api/features/discovery/introspection/

[3]: /analytics/graphql-api/getting-started/
Loading