Skip to content

Conversation

ToriLindsay
Copy link
Contributor

@ToriLindsay ToriLindsay commented Sep 12, 2025

We recently deprecated the "Contributing" README tab and redirected to the new Contributing section in the Style Guide. This extra information needed a new home so I merged it here into the existing GraphQL API Explorer section.

For reference, below is the content from the old "Contributing" README tab that I merged in. (You can also view it here: #25049 )

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. For example:

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 a user selects the Run in GraphQL API Explorer button, 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.

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"}

Copy link
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/style-guide/ @dcpena, @cloudflare/pcx-technical-writing

Copy link
Contributor

github-actions bot commented Sep 12, 2025

@ToriLindsay ToriLindsay enabled auto-merge (squash) September 12, 2025 08:50
@ToriLindsay ToriLindsay merged commit 6539d5e into production Sep 12, 2025
8 checks passed
@ToriLindsay ToriLindsay deleted the tori/graphql-api-explorer-content-merge branch September 12, 2025 09:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants