Merge pull request #2393 from buildkite/graphql-cookbooks

Split up GraphQL cookbooks

Author: mbelton-buildkite

data/nav_graphql.yml

@@ -4,7 +4,23 @@
 - name: Console and CLI tutorial
   path: apis/graphql/graphql-tutorial
 - name: Cookbook
-  path: apis/graphql/graphql-cookbook
+  children:
+  - name: Overview
+    path: apis/graphql/graphql-cookbook
+  - name: Pipelines
+    path: apis/graphql/cookbooks/pipelines
+  - name: Builds
+    path: apis/graphql/cookbooks/builds
+  - name: Jobs
+    path: apis/graphql/cookbooks/jobs
+  - name: Agents
+    path: apis/graphql/cookbooks/agents
+  - name: Clusters
+    path: apis/graphql/cookbooks/clusters
+  - name: Organizations
+    path: apis/graphql/cookbooks/organizations
+  - name: Teams
+    path: apis/graphql/cookbooks/teams
 - name: Limits
   path: apis/graphql/graphql-resource-limits
 - name: Queries

pages/apis/api_differences.md

@@ -20,25 +20,25 @@ On this page, we've collected the known limitation where some API features are o
 
 ## Features only available in the GraphQL API
 
-* <%= pill "AGENTS", "agents" %> [Get a list of agent token IDs (agent tokens are currently only available via GraphQL)](/docs/apis/graphql/graphql-cookbook#agents-get-a-list-of-agent-token-ids).
-* <%= pill "BUILDS", "builds" %> [Get all environment variables set on a build](/docs/apis/graphql/graphql-cookbook#builds-get-all-environment-variables-set-on-a-build).
-* <%= pill "BUILDS", "builds" %> [Increase the next build number](/docs/apis/graphql/graphql-cookbook#builds-increase-the-next-build-number).
-* <%= pill "BUILDS", "builds" %> [Get build info by ID] (/docs/apis/graphql/graphql-cookbook#builds-get-build-info-by-id).
-* <%= pill "JOBS", "jobs" %> [Get all jobs in a given queue for a given timeframe](/docs/apis/graphql/graphql-cookbook#jobs-get-all-jobs-in-a-given-queue-for-a-given-timeframe).
-* <%= pill "JOBS", "jobs" %> [Get all jobs in a particular concurrency group](/docs/apis/graphql/graphql-cookbook#jobs-get-all-jobs-in-a-particular-concurrency-group).
+* <%= pill "AGENTS", "agents" %> [Get a list of agent token IDs (agent tokens are currently only available via GraphQL)](/docs/apis/graphql/cookbooks/agents#get-a-list-of-agent-token-ids).
+* <%= pill "BUILDS", "builds" %> [Get all environment variables set on a build](/docs/apis/graphql/cookbooks/builds#get-all-environment-variables-set-on-a-build).
+* <%= pill "BUILDS", "builds" %> [Increase the next build number](/docs/apis/graphql/cookbooks/builds#increase-the-next-build-number).
+* <%= pill "BUILDS", "builds" %> [Get build info by ID] (/docs/apis/graphql/cookbooks/builds#get-build-info-by-id).
+* <%= pill "JOBS", "jobs" %> [Get all jobs in a given queue for a given timeframe](/docs/apis/graphql/cookbooks/jobs#get-all-jobs-in-a-given-queue-for-a-given-timeframe).
+* <%= pill "JOBS", "jobs" %> [Get all jobs in a particular concurrency group](/docs/apis/graphql/cookbooks/jobs#get-all-jobs-in-a-particular-concurrency-group).
 * <%= pill "JOBS", "jobs" %> list job events.
 * <%= pill "JOBS", "jobs" %> [Cancel a job](/docs/apis/graphql/schemas/mutation/jobtypecommandcancel).
-* <%= pill "ORGANIZATIONS", "organizations" %> [Remove users from an organization](/docs/apis/graphql/graphql-cookbook#organizations-delete-an-organization-member).
-* <%= pill "ORGANIZATIONS", "organizations" %> Manage teams - [add](/docs/apis/graphql/graphql-cookbook#teams-add-an-existing-organization-user-to-a-team) or [remove](/docs/apis/graphql/graphql-cookbook#teams-remove-a-team-member) a team member. Most of the team management features are only available for GraphQL. The REST API can only list teams and can create pipelines in teams.
+* <%= pill "ORGANIZATIONS", "organizations" %> [Remove users from an organization](/docs/apis/graphql/cookbooks/organizations#delete-an-organization-member).
+* <%= pill "ORGANIZATIONS", "organizations" %> Manage teams - [add](/docs/apis/graphql/cookbooks/teams#add-an-existing-organization-user-to-a-team) or [remove](/docs/apis/graphql/cookbooks/teams#remove-a-team-member) a team member. Most of the team management features are only available for GraphQL. The REST API can only list teams and can create pipelines in teams.
 * <%= pill "ORGANIZATIONS", "organizations" %> [Set up SSO](/docs/integrations/sso/sso-setup-with-graphql).
-* <%= pill "ORGANIZATIONS", "organizations" %> [Remove pipeline edit access from existing teams](/docs/apis/graphql/graphql-cookbook#teams-set-teams-pipeline-edit-access-to-read-only-or-build-and-read).
-* <%= pill "PIPELINES", "pipelines" %> [Get all the pipeline metrics from the dashboard from the API](/docs/apis/graphql/graphql-cookbook#pipelines-get-pipeline-metrics).
-* <%= pill "PIPELINES", "pipelines" %> [Get the last build's creation date within every pipeline](/docs/apis/graphql/graphql-cookbook#builds-get-the-creation-date-of-the-most-recent-build-in-every-pipeline).
-* <%= pill "PIPELINES", "pipelines" %> [Count the number of builds on a branch](/docs/apis/graphql/graphql-cookbook#builds-count-the-number-of-builds-on-a-branch).
-* <%= pill "PIPELINES", "pipelines" %> [Get the creation date of the most recent build in every pipeline](/docs/apis/graphql/graphql-cookbook#builds-get-the-creation-date-of-the-most-recent-build-in-every-pipeline).
+* <%= pill "ORGANIZATIONS", "organizations" %> [Remove pipeline edit access from existing teams](/docs/apis/graphql/cookbooks/teams#set-teams-pipeline-edit-access-to-read-only-or-build-and-read).
+* <%= pill "PIPELINES", "pipelines" %> [Get all the pipeline metrics from the dashboard from the API](/docs/apis/graphql/cookbooks/pipelines#get-pipeline-metrics).
+* <%= pill "PIPELINES", "pipelines" %> [Get the last build's creation date within every pipeline](/docs/apis/graphql/cookbooks/builds#get-the-creation-date-of-the-most-recent-build-in-every-pipeline).
+* <%= pill "PIPELINES", "pipelines" %> [Count the number of builds on a branch](/docs/apis/graphql/cookbooks/builds#count-the-number-of-builds-on-a-branch).
+* <%= pill "PIPELINES", "pipelines" %> [Get the creation date of the most recent build in every pipeline](/docs/apis/graphql/cookbooks/builds#get-the-creation-date-of-the-most-recent-build-in-every-pipeline).
 * <%= pill "PIPELINES", "pipelines" %> Filter results from pipeline listings.
 * <%= pill "PIPELINES", "pipelines" %> Create and manage pipeline schedules.
-* <%= pill "USERS", "users" %> [Invite a user into a specific team with a specific role and permissions set](/docs/apis/graphql/graphql-cookbook#organizations-create-a-user-add-them-to-a-team-and-set-user-permissions).
+* <%= pill "USERS", "users" %> [Invite a user into a specific team with a specific role and permissions set](/docs/apis/graphql/cookbooks/organizations#create-a-user-add-them-to-a-team-and-set-user-permissions).
 
 ## Known missing API features
 

pages/apis/graphql/cookbooks/agents.md

@@ -0,0 +1,83 @@
+# Agents
+
+A collection of common tasks with agents using the GraphQL API.
+
+You can test out the Buildkite GraphQL API using the [Buildkite explorer](https://graphql.buildkite.com/explorer). This includes built-in documentation under the _Docs_ panel.
+
+## Get a list of agent token IDs
+
+Get the first five agent token IDs for an organization.
+
+```graphql
+query token {
+  organization(slug: "organization-slug") {
+    id
+    name
+    agentTokens(first: 5) {
+      edges {
+        node {
+          id
+          description
+        }
+      }
+    }
+  }
+}
+```
+
+## Search for agents in an organization
+
+```graphql
+query SearchAgent {
+   organization(slug:"organization-slug") {
+    agents(first:500, search:"search-string") {
+      edges {
+        node {
+          name
+          hostname
+          version
+        }
+      }
+    }
+  }
+}
+```
+
+## Revoke an agent token
+
+Revoking an agent token means no new agents can start using the token. It does not affect any connected agents.
+
+First, get the token ID. You can find it in the Buildkite dashboard, in _Agents_ > _Reveal Agent Token_, or you can retrieve a list of agent token IDs using this query:
+
+```graphql
+query GetAgentTokenID {
+  organization(slug: "organization-slug") {
+    agentTokens(first:50) {
+      edges {
+        node {
+          id
+          uuid
+          description
+        }
+      }
+    }
+  }
+}
+```
+
+Then, using the token ID, revoke the agent token:
+
+```graphql
+mutation {
+  agentTokenRevoke(input: {
+    id: "token-id",
+    reason: "A reason"
+  }) {
+    agentToken {
+      description
+      revokedAt
+      revokedReason
+    }
+  }
+}
+```