Merge pull request #2612 from buildkite/jh/docs/team-api-docs-overarching-branch

[FDN-3587] Add new Orgs / Teams / Suites REST API Documentation

Author: jfhinchcliffe

app/models/beta_pages.rb

@@ -1,7 +1,13 @@
 class BetaPages
   def self.all
     [
-      'pipelines/cluster-queue-metrics'
+      'pipelines/cluster-queue-metrics',
+      'apis/rest-api/team-pipelines',
+      'apis/rest-api/organizations/members',
+      'apis/rest-api/teams',
+      'apis/rest-api/teams/members',
+      'apis/rest-api/teams/pipelines',
+      'apis/rest-api/teams/suites'
     ]
   end
 end

config/routes.rb

@@ -2,6 +2,7 @@
   # Pages and guides that have been renamed (and we don't want to break old URLs)
   get "/docs/api",                                to: redirect("/docs/apis/rest-api")
   get "/docs/api/accounts",                       to: redirect("/docs/apis/rest-api/organizations")
+  get "/docs/api/organizations",                  to: redirect("/docs/apis/rest-api/organizations")
   get "/docs/api/projects",                       to: redirect("/docs/apis/rest-api/pipelines")
   get "/docs/api/*page",                          to: redirect("/docs/apis/rest-api/%{page}")
   get "/docs/apis/graphql-tutorial",              to: redirect("/docs/apis/graphql/graphql-tutorial")

data/nav.yml

@@ -310,7 +310,7 @@
           path: "clusters/queue-metrics"
     - name: "Hosted agents"
       pill: "private trials"
-      children: 
+      children:
         - name: "Overview"
           path: "pipelines/hosted-agents/overview"
         - name: "Mac hosted agents"
@@ -429,8 +429,33 @@
           path: "apis/rest-api"
         - name: "Limits"
           path: "apis/rest-api/limits"
-        - name: "Pipelines REST API"
+        - name: "Agent"
+          children:
+            - name: "Overview"
+              path: "apis/agent-api"
+            - name: "Metrics"
+              path: "apis/agent-api/metrics"
+        - name: "Analytics"
           children:
+            - name: "Flaky tests"
+              path: "apis/rest-api/analytics/flaky-tests"
+            - name: "Runs"
+              path: "apis/rest-api/analytics/runs"
+            - name: "Suites"
+              path: "apis/rest-api/analytics/suites"
+            - name: "Tests"
+              path: "apis/rest-api/analytics/tests"
+        - name: "Organizations"
+          children:
+            - name: "Overview"
+              path: "apis/rest-api/organizations"
+            - name: "Members"
+              path: "apis/rest-api/organizations/members"
+              pill: "beta"
+        - name: "Pipelines "
+          children:
+            - name: "Overview"
+              path: "apis/rest-api/pipelines"
             - name: "Access token"
               path: "apis/rest-api/access-token"
             - name: "Agents"
@@ -449,32 +474,21 @@
               path: "apis/rest-api/jobs"
             - name: "Meta"
               path: "apis/rest-api/meta"
-            - name: "Organizations"
-              path: "apis/rest-api/organizations"
-            - name: "Pipelines"
-              path: "apis/rest-api/pipelines"
             - name: "Pipeline templates"
               path: "apis/rest-api/pipeline-templates"
-            - name: "Teams"
-              path: "apis/rest-api/teams"
             - name: "User"
               path: "apis/rest-api/user"
-        - name: "Agent REST API"
+        - name: "Teams"
+          pill: "beta"
           children:
             - name: "Overview"
-              path: "apis/agent-api"
-            - name: "Metrics"
-              path: "apis/agent-api/metrics"
-        - name: "Analytics REST API"
-          children:
-            - name: "Flaky tests"
-              path: "apis/rest-api/analytics/flaky-tests"
-            - name: "Runs"
-              path: "apis/rest-api/analytics/runs"
+              path: "apis/rest-api/teams"
+            - name: "Members"
+              path: "apis/rest-api/teams/members"
+            - name: "Pipelines"
+              path: "apis/rest-api/teams/pipelines"
             - name: "Suites"
-              path: "apis/rest-api/analytics/suites"
-            - name: "Tests"
-              path: "apis/rest-api/analytics/tests"
+              path: "apis/rest-api/teams/suites"
     - name: "GraphQL"
       children: []
     - name: "Webhooks"

pages/agent/v3/tokens.md

@@ -49,7 +49,7 @@ To create an agent token for a cluster using the Buildkite interface:
 
 To [create an agent token](/docs/apis/rest-api/clusters#agent-tokens-create-a-token) using the [REST API](/docs/apis/rest-api), run the following example `curl` command:
 
-```curl
+```bash
 curl -H "Authorization: Bearer $TOKEN" \
   -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens" \
   -H "Content-Type: application/json" \
@@ -153,7 +153,7 @@ To update a cluster's agent token using the Buildkite interface:
 
 To [update an agent token](/docs/apis/rest-api/clusters#agent-tokens-update-a-token) using the [REST API](/docs/apis/rest-api), run the following example `curl` command:
 
-```curl
+```bash
 curl -H "Authorization: Bearer $TOKEN" \
   -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}" \
   -H "Content-Type: application/json" \
@@ -253,7 +253,7 @@ To revoke a cluster's agent token using the Buildkite interface:
 
 To [revoke an agent token](/docs/apis/rest-api/clusters#agent-tokens-revoke-a-token) using the [REST API](/docs/apis/rest-api), run the following example `curl` command:
 
-```curl
+```bash
 curl -H "Authorization: Bearer $TOKEN" \
   -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens/{id}"
 ```

pages/apis/agent_api/metrics.md

@@ -10,8 +10,9 @@ The Metrics API endpoint provides information on idle and busy agents, jobs, and
 
 Get agent metrics
 
-```
-curl -H "Authorization: Token $BUILDKITE_AGENT_TOKEN" "https://agent.buildkite.com/v3/metrics"
+```bash
+curl -H "Authorization: Bearer $BUILDKITE_AGENT_TOKEN" \
+  -X GET "https://agent.buildkite.com/v3/metrics"
 ```
 
 ```json

pages/apis/descriptions/_rest_agent_token_id.md

@@ -7,6 +7,7 @@
 
     * By running the [List tokens](/docs/apis/rest-api/clusters#agent-tokens-list-tokens) REST API query and obtain this value from the `id` in the response associated with the description of your token (specified by the `description` value in the response). For example:
 
-        ```curl
-        curl -H "Authorization: Bearer $TOKEN" "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens"
+        ```bash
+        curl -H "Authorization: Bearer $TOKEN" \
+          - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/tokens"
         ```

pages/apis/descriptions/_rest_cluster_id.md

@@ -6,6 +6,7 @@
 
     * By running the [List clusters](/docs/apis/rest-api/clusters#clusters-list-clusters) REST API query and obtain this value from the `id` in the response associated with the name of your target cluster (specified by the `name` value in the response). For example:
 
-        ```curl
-        curl -H "Authorization: Bearer $TOKEN" "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
+        ```bash
+        curl -H "Authorization: Bearer $TOKEN" \
+          - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
         ```

pages/apis/descriptions/_rest_cluster_id_body.md

@@ -6,6 +6,7 @@
 
     * By running the [List clusters](/docs/apis/rest-api/clusters#clusters-list-clusters) REST API query and obtain this value from the `id` in the response associated with the name of your target cluster (specified by the `name` value in the response). For example:
 
-        ```curl
-        curl -H "Authorization: Bearer $TOKEN" "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
+        ```bash
+        curl -H "Authorization: Bearer $TOKEN"
+          - X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters"
         ```

pages/apis/descriptions/_rest_org_slug.md

@@ -4,6 +4,7 @@
 
     * By running the [List organizations](/docs/apis/rest-api/organizations#list-organizations) REST API query to obtain this value from `slug` in the response. For example:
 
-        ```curl
-        curl -H "Authorization: Bearer $TOKEN" "https://api.buildkite.com/v2/organizations"
+        ```bash
+        curl -H "Authorization: Bearer $TOKEN" \
+          - X GET "https://api.buildkite.com/v2/organizations"
         ```

pages/apis/rest_api.md

@@ -6,7 +6,6 @@ The current version of the Buildkite API is v2.
 
 For the list of existing disparities between the REST API and the GraphQL API, see [API differences](/docs/apis/api-differences).
 
-
 ## Schema
 
 All API access is over HTTPS, and accessed from the `api.buildkite.com` domain. All data is sent as JSON.
@@ -25,16 +24,18 @@ curl https://api.buildkite.com
 
 Some API endpoints accept query string parameters which are added to the end of the URL. For example, the [builds listing APIs](/docs/api/builds#list-all-builds) can be filtered by `state` using the following `curl` command:
 
-```
-curl "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?state=passed"
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?state=passed"
 ```
 
 ## Request body properties
 
 Some API requests accept JSON request bodies for specifying data. For example, the [build create API](/docs/api/builds#create-a-build) can be passed the required properties using the following `curl` command:
 
-```
-curl -X POST "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds" \
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  -X POST "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds" \
   -H "Content-Type: application/json" \
   -d '{
     "key": "value"
@@ -45,25 +46,26 @@ The data encoding is assumed to be `application/json`. Unless explicitly stated
 
 ## Authentication
 
-You can authenticate with the Buildkite API using access tokens.
+You can authenticate with the Buildkite API using access tokens, represented by the value `$TOKEN` throughout this documentation.
 
 API access tokens allow to call the API without using your username and password. They can be created on your <a href="<%= url_helpers.user_access_tokens_url %>" rel="nofollow">API access tokens</a> page, limited to individual organizations and permissions, and revoked at any time from the web interface [or the REST API](/docs/apis/rest-api/access-token#revoke-the-current-token).
 
 To authenticate using a token, set the <code>Authorization</code> HTTP header to the word <code>Bearer</code>, followed by a space, followed by the access token. For example:
 
 ```bash
-curl -H "Authorization: Bearer $TOKEN" https://api.buildkite.com/v2/user
+curl -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/user"
 ```
 
->🚧 Basic authentication
-> Access using basic HTTP authentication is no longer available.
+Access using basic HTTP authentication is not supported.
 
 ## Pagination
 
 For endpoints which support pagination, the pagination information can be found in the `Link` HTTP response header containing zero or more of `next`, `prev`, `first` and `last`.
 
 ```bash
-curl -i "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds"
+curl -i -H "Authorization: Bearer $TOKEN" \
+  -X GET "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds"
 ```
 
 ```