PCX-1086 Analytics GraphQL Getting started update

Author: ariordan-docforce

products/analytics/package.json

@@ -4,11 +4,11 @@
     "cloudflare-docs-engine": "git+https://github.com/cloudflare/cloudflare-docs-engine.git"
   },
   "scripts": {
-    "bootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh bootstrap",
-    "build": "node_modules/cloudflare-docs-engine/bin/commands.sh build",
-    "develop": "node_modules/cloudflare-docs-engine/bin/commands.sh develop",
-    "ghactionsbootstrap": "node_modules/cloudflare-docs-engine/bin/commands.sh ghactionsbootstrap",
-    "savechanges": "node_modules/cloudflare-docs-engine/bin/commands.sh savechanges",
-    "serve": "node_modules/cloudflare-docs-engine/bin/commands.sh serve"
+    "bootstrap": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh bootstrap",
+    "build": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh build",
+    "develop": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh develop",
+    "ghactionsbootstrap": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh ghactionsbootstrap",
+    "savechanges": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh savechanges",
+    "serve": "sh ./node_modules/cloudflare-docs-engine/bin/commands.sh serve"
   }
 }

products/analytics/src/content/graphql-api/getting-started/authentication/api-key-auth.md

@@ -1,6 +1,6 @@
 ---
 title: Authenticate with a Cloudflare API key
-order: 20
+order: 30
 ---
 
 # Authenticate with a Cloudflare API key
@@ -9,35 +9,3 @@ API keys are unique to each Cloudflare user and used only for authentication. An
 
 * Learn how to [find your API Key](https://support.cloudflare.com/hc/articles/200167836) in the Cloudflare Dashboard
 * Learn how to [retrieve your API Key](https://api.cloudflare.com/#getting-started-requests) using the Cloudflare API
-
-## Edit HTTP headers for GraphiQL authentication
-
-1. Launch _GraphiQL_
-
-2. Click **Edit HTTP Headers**
-   ![ ](../../../static/images/GraphiQL-edit-http-headers.png)
-   The _Edit HTTP Headers_ window appears.
-   ![ ](../../../static/images/GraphiQL-edit-http-headers-window.png)
-
-3. Click **Add Header**
-   ![ ](../../../static/images/GraphiQL-add-header.png)
-
-4. Enter **X-AUTH-EMAIL** in the _Header name_ field and your email address registered with Cloudflare in the _Header value_ field, and click **Save**
-
-5. Click **Add Header**
-
-6. Enter **X-AUTH-KEY** in the _Header Name_ field, then paste your Global API Key in the _Header value_ field, and click **Save**
-   ![ ](../../../static/images/GraphiQL-edit-http-headers-complete.png)
-
-7. Click anywhere outside the _Edit HTTP Headers_ window in _GraphiQL_ to return to the _Untitled Query 1_ tab
-
-8. Enter `https://api.cloudflare.com/client/v4/graphql` in the _GraphQL Endpoint_ field
-   ![ ](../../../static/images/GraphiQL-response-pane.png)
-
-<Aside type='note' header='Note'>
-
-The right-side response pane is empty when you enter your information correctly. An error displays when there are problems with your header credentials.
-
-</Aside>
-
-Now that you have configured authentication with a Cloudflare API key, you are ready to run queries using _GraphiQL_.

products/analytics/src/content/graphql-api/getting-started/authentication/api-token-auth.md

@@ -1,6 +1,6 @@
 ---
 title: Configure an Analytics API token
-order: 30
+order: 20
 ---
 
 # Configure an Analytics API token
@@ -48,7 +48,7 @@ To configure a custom token, follow these steps:
 
   ![Create Custom Token page](../../../static/images/create-custom-api-token.png)
 
-1. Use the **Token name** text input to enter a descriptive name for your token.
+1. Enter a descriptive name for your token in the **Token name** text input field.
 
 1. To configure access to the GraphQL Analytics API, use the **Permissions** drop-down lists. To set permissions for the GraphQL Analytics API, select _Analytics_ from the second drop-down list.
 
@@ -70,7 +70,7 @@ To configure a custom token, follow these steps:
 
 1. Click **Continue to summary**.
 
-The next section of this walk through shows you how to [review and test your API token](#review-and-test-your-api-token).
+The next section of this walkthrough shows you how to [review and test your API token](#review-and-test-your-api-token).
 
 ## Review and create your API token
 
@@ -92,7 +92,7 @@ To copy the token to your device's clipboard, click the **Copy** button.
 
 <Aside type='note' header='Note'>
 
-The confirmation page is the only time that you can see the token, so make sure you store it safely, since anyone who has token can use it to access your data.
+The confirmation page is the only time that you can see the token, so make sure you store it safely, since anyone who has the token can use it to access your data.
 
 If you lose the secret, you can [regenerate the token from the API Tokens page](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys#12345681), so that you do not have to configure all the permissions again.
 

products/analytics/src/content/graphql-api/getting-started/authentication/graphql-client-headers.md

@@ -0,0 +1,33 @@
+---
+title: Configure GraphQL client endpoint and HTTP headers
+order: 40
+---
+
+# Configure GraphQL client endpoint and HTTP headers
+
+1. Launch _GraphiQL_.
+1. Click **Edit HTTP Headers**.
+   ![Click Edit HTTP Headers](../../../static/images/GraphiQL-edit-http-headers.png)
+   The _Edit HTTP Headers_ window appears.
+   ![Edit HTTP Headers Window](../../../static/images/GraphiQL-edit-http-headers-window.png)
+1. Click **Add Header**.
+   ![Click Add Header](../../../static/images/GraphiQL-add-header.png)
+1. Enter **X-AUTH-EMAIL** in the _Header name_ field and your email address registered with Cloudflare in the _Header value_ field, and click **Save**.
+1. To configure authentication, click **Add Header**. You can use Cloudflare Analytics API token authentication (recommended) or Cloudflare API key authentication.
+   * **Token authentication**:
+   Enter **Authorization** in the _Header Name_ field, and enter **Bearer {your-analytics-token}**  in the _Header value_ field, then click **Save**.
+   ![HTTP Headers](../../../static/images/GraphiQL-edit-http-headers-token.png)
+   * **Key authentication**:
+   Enter **X-AUTH-KEY** in the _Header Name_ field, and paste your Global API Key in the _Header value_ field, then click **Save**.
+   ![HTTP Headers](../../../static/images/GraphiQL-edit-http-headers-complete.png)
+1. Click anywhere outside the _Edit HTTP Headers_ window in _GraphiQL_ to close it and return to the main _GraphiQL_ display.
+1. Enter `https://api.cloudflare.com/client/v4/graphql` in the _GraphQL Endpoint_ field
+   ![Edit GraphQL Endpoint](../../../static/images/GraphiQL-response-pane.png)
+
+<Aside type='note' header='Note'>
+
+The right-side response pane is empty when you enter your information correctly. An error displays when there are problems with your header credentials.
+
+</Aside>
+
+Now that you have configured authentication with a Cloudflare API key, you are ready to run queries using _GraphiQL_.

products/analytics/src/content/graphql-api/getting-started/authentication/index.md

@@ -5,9 +5,9 @@ order: 10
 
 # Authentication
 
-Cloudflare separates service configuration by zone. When there are multiple accounts each with many zones, it is important to restrict GraphQL Analytics API access to only those account and zone resources that are relevant for the task at hand.
+Cloudflare separates service configuration by zone. When there are multiple accounts, each with many zones, it is important to restrict GraphQL Analytics API access to only those account and zone resources that are relevant for the task at hand.
 
-To secure access your GraphQL Analytics data, use a Cloudflare API key or token to authenticate an API request.
+To secure access to your GraphQL Analytics data, use a Cloudflare API key or token to authenticate an API request.
 
 This table outlines the differences between Cloudflare API keys and tokens:
 
@@ -21,20 +21,20 @@ This table outlines the differences between Cloudflare API keys and tokens:
       </tr>
   </thead>
   <tbody>
+      <tr>
+        <td><a href='https://developers.cloudflare.com/api/tokens/create'>API Tokens</a></td>
+        <td>Cloudflare recommends API Tokens as the preferred way to interact with Cloudflare APIs. You can configure the scope of tokens to limit access to account and zone resources, and you can define the Cloudflare APIs to which the token authorizes access.</td>
+      </tr>
       <tr>
         <td><a href='https://developers.cloudflare.com/api/keys'>API Keys</a></td>
         <td><p>Unique to each Cloudflare user and used only for authentication. API keys do not authorize access to accounts or zones.</p>
         <p>Use the Global API Key for authentication. Only use the Origin CA Key when you create origin certificates through the API.</p></td>
       </tr>
-      <tr>
-        <td><a href='https://developers.cloudflare.com/api/tokens/create'>API Tokens</a></td>
-        <td>Cloudflare recommends API Tokens as the preferred way to interact with Cloudflare APIs. You can configure the scope of tokens to limit access to account and zone resources, and you can define the Cloudflare APIs to which the token authorizes access.</td>
-      </tr>
   </tbody>
 </table>
 
 </TableWrap>
 
-To find and retrieve API keys, as well as edit HTTP headers for authentication in GraphiQL, see [_Authenticate with a Cloudflare API key_](/graphql-api/getting-started/authentication/api-key-auth/).
-
 To create and configure GraphQL Analytics API tokens, see [_Configure an Analytics API token_](/graphql-api/getting-started/authentication/api-token-auth/).
+
+To find and retrieve API keys, as well as edit HTTP headers for authentication in GraphiQL, see [_Authenticate with a Cloudflare API key_](/graphql-api/getting-started/authentication/api-key-auth/).

products/analytics/src/content/graphql-api/getting-started/compose-graphql-query.md

@@ -0,0 +1,65 @@
+---
+title: Create a query in a GraphQL client
+order: 50
+---
+
+# Create a query in a GraphQL client
+
+You can use a GraphQL client to build and execute queries to the GraphQL API endpoint. The example below uses the GraphiQL client.
+
+Before you begin, configure the API endpoint and HTTP headers in the GraphQL client.
+
+Click on the editing pane of GraphiQL and add the following base query:
+
+```json
+query {
+  viewer {
+    zones(filter: { zoneTag: "{zone-id}"}) {
+
+    }
+  }
+}
+```
+
+To explore the documentation for the nodes and fields in the Cloudflare GraphQL schema, click **Docs** to open the _Documentation Explorer_ pane.
+
+The GraphiQL client has auto completion, to assist query building. Place your cursor on the line under "zones" and start typing a word: a popup window appears, listing all the possible fields that contain that word. For example, if you type `firewall`, the popup displays the fields that return firewall information:
+
+![firewall nodes](../../static/images/create-query-fw-data-set.png)
+
+The text at the bottom of the list displays a short description of the data that the node returns.
+
+Select the field you want to use and insert it into your query: either click the item in the list, or scroll using  arrow keys and hit return.
+
+Hover your mouse over a field to open a popup window showing the documentation for that field. The following popup window appears when you hover over the `firewallEventsAdaptive` field:
+
+![Autocomplete popup](../../static/images/create-query-fw-data-set-description.png)
+
+Click on the node name (blue text) to display information about the field, including the required parameters, in the _Documentation Explorer_ pane.
+
+Click on the type definition (gold text) to display information about the field type in the _Documentation Explorer_ pane.
+
+Add the required parameters for the field in the editing pane: type the open parenthesis character, `(`, after the field name. GraphiQL inserts the closing parenthesis and opens a popup window with a list of required parameters:
+
+![GraphiQL filter popup](../../static/images/create-query-fw-data-set-filter.png)
+
+Configure the required parameters.
+
+To add the data fields that you want to display, type the opening bracket `{` after the closing parenthesis containing parameters. GraphiQL automatically inserts the closing bracket. For readability, hit the return key between the brackets.
+
+Click the field type definition to display the list of fields in in the  _Documentation Explorer_ pane:
+
+![List of fields](../../static/images/create-query-fw-data-set-field-type.png)
+
+Start typing the name of a field that you want to fetch, to open an auto-complete list. Once you have entered all the fields you want, click the **Play** button to submit the query. The response pane contains the data fetched from the Cloudflare GraphQL API endpoint.
+
+The GraphiQL client allows you to create variables to use in the query.
+In the following example, the _Query variables_ pane contains a variable that represents a zone ID:
+
+```json
+{"zoneTag":"xxxxxxxxx"}
+```
+
+Use `$zoneTag` to refer to the variable in a query.
+
+![GraphiQL response](../../static/images/create-query-fw-data-set-play.png)

products/analytics/src/content/graphql-api/getting-started/execute-graphql-query.md

@@ -0,0 +1,68 @@
+---
+title: Use curl to query the GraphQL API
+order: 60
+---
+
+# Use CURL to query the GraphQL API
+
+You can submit a query you built up in the GraphiQL client as a payload in the `data` field of a POST request to the GraphQL API.
+
+The advantage of executing the request as a CURL request is that you can redirect the response to a file, and execute other post processing methods.
+
+The GraphQL endpoint requires valid JSON, so you must pass the query as the _value_ part of a JSON _key/value_ pair with a key named "query".
+
+Pass the list of variables in another JSON _key:value_ pair with a key named "variables".
+
+The script below returns the firewall events in one zone over the last 24 hours:
+
+```
+#!/bin/bash
+#
+# This script fetches the last 24 hours of firewall events for the ZoneID passed
+# in as the first parameter using the global key passed in as the second parameter.
+######################################################################################
+ 
+ZoneID="$1"
+global_key="$2"
+Email="[email protected]"
+#
+# Calculate 24 hours back and produce the start and end times in the appropriate format.
+back_seconds=60*60*24  # 24 hours
+end_epoch=$(date +'%s')
+let start_epoch=$end_epoch-$back_seconds
+start_date=$(date --date="@$start_epoch" +'%Y-%m-%dT%H:%m:%SZ')
+end_date=$(date --date="@$end_epoch" +'%Y-%m-%dT%H:%m:%SZ')
+ 
+PAYLOAD='{ "query":
+  "query {
+    viewer {
+      zones(filter: { zoneTag: $zoneTag }) {
+      firewallEventsAdaptive(
+        filter: $filter
+        limit: 10000
+        orderBy: [datetime_DESC, rayName_DESC]
+      ) {
+          action,
+          datetime,
+          rayName,
+          clientRequestHTTPHost,
+          userAgent
+        }
+      }
+    }
+  }",'
+PAYLOAD="$PAYLOAD
+
+  \"variables\": {
+    \"zoneTag\": \"$ZoneID\",
+    \"filter\": {
+      \"datetime_gt\": \"$start_date\",
+      \"datetime_leq\": \"$end_date\"
+    }
+  }
+}"
+
+# Run query to GraphQL API endpoint
+
+curl -s -X POST -H "Content-Type: application/json" -H "X-Auth-Email: $Email" -H  X-Auth-Key: $global_key --data "$(echo $PAYLOAD)" https://api.cloudflare.com/client/v4/graphql/
+```

products/analytics/src/content/graphql-api/getting-started/explore-graphql-schema.md

@@ -0,0 +1,55 @@
+---
+title: Explore the GraphQL schema
+order: 40
+---
+
+# Explore the GraphQL schema in the GraphQL client
+
+You can explore the schema of the Coudflare GraphQL endpoint in the the GraphQL client. The examples below use the GraphiQL client.
+
+Before you begin, configure the API endpoint and HTTP headers in the GraphQL client.
+
+Click **Docs** to open the _Documentation Explorer_ pane.
+
+A list of available nodes displays. The nodes in the list follow this syntax:
+
+```
+node-name: node-type-definition
+```
+
+Click on the _type definition_ of a node to view the fields that it provides. The _Documentation Explorer_ pane also displays descriptions of the nodes.
+
+When you first open the _Documentation Explorer_ pane, the **mutation** and **query** nodes display:
+
+![Mutation and query nodes](../../static/images/docs-query.png)
+
+* **query** is the name of the node.
+* **Query** is the type definition of the node.
+
+Click the **Query** type definition. The _Documentation Explorer_ panel displays the fields that the **query** node provides: **cost** and **viewer**.
+
+![Cost and viewer fields](../../static/images/docs-viewer.png)
+
+Click on the type definition of **viewer** to list the fields of the **viewer** node. The **viewer** node fields include nodes that allow you to query **accounts** or **zones** data:
+
+![viewer fields](../../static/images/docs-zone-filter.png)
+
+The **accounts** and **zones** nodes take arguments to specify what data set to query.
+For the **zones** node you can provide a **filter** of **ZoneFilter_InputObject** type. To view the fields to specify in the filter, click **ZoneFilter_InputObject**.
+
+To limit the amount of search results that the query returns, click **limit**.
+
+To view a list of the fields within a zone, click on the **zones** type definition after the colon in the **zones** field:
+
+![Zones type definition](../../static/images/docs-zone.png)
+
+A list of _search nodes_ appears, with a brief description of their behavior and a list of valid arguments.
+Arguments that end with an exclamation mark ("!") are required.
+
+![Search nodes](../../static/images/docs-fw-data-set.png)
+
+Refer to [Data Sets (tables)](/graphql-api/features/data-sets) for details on nomenclature and behavior of these nodes.
+
+To view the fields that a node provides, click on its type definition. If you click on the **ZoneFirewallEventsAdaptive** type definition in the  **firewallEventsAdaptive** node, a list of fields is displayed:
+
+![ZoneFirewallEventsAdaptive type definition](../../static/images/docs-fw-fields-list.png)

products/analytics/src/content/graphql-api/getting-started/index.md

@@ -9,5 +9,8 @@ Use these articles to get started with the Cloudflare GraphQL Analytics API:
 
 * [_Authentication_](/graphql-api/getting-started/authentication) walks you through the options and the steps required to successfully set up your access to Cloudflare API.
 * [_Querying basics_](/graphql-api/getting-started/querying-basics) brings you simple query examples for you to start exploring the GraphQL Analytics API.
+* [_Explore the GraphQL schema in the GraphQL client_](/graphql-api/getting-started/explore-graphql-schema/) introduces the introspective documentation in the GraphQL API.
+* [_Create a query in a GraphQL client_](/graphql-api/getting-started/compose-graphql-query/) describes how to build and run a query against the Cloudflare GraphQL API in the GraphiQL client.
+* [_Use curl to query the GraphQL API_](/graphql-api/getting-started/execute-graphql-query/) walks you through running a query against the Cloudflare GraphQL API from the command line.
 
 For examples of how to build your own GraphQL Analytics dashboard and query specific information, such as Firewall and Workers events, see [_Tutorials_](/graphql-api/tutorials).