Turbot DocsGetting StartedConceptsGuidesIntegrationsMods7-minute LabsPolicy SettingsCalculated PoliciesCLICustom ModsGraphQLTerraformFAQsReferenceRelease NotesTurbot.comEnterprise

GraphQL in 7 minutes
Goal Query Turbot using GraphQL and learn how to explore the GraphQL API.
Time 7 minutes

Overview

GraphQL is the native query language for the Turbot API.

In this exercise, you will explore the Turbot GraphQL API via the GraphiQL interface built into the Turbot Console.

By the end of this lab, you will be able to query the Turbot API via GraphQL, filter and page through results, and leverage the basic features of the GraphiQL editor.

Open GraphiQL for your Turbot Workspace

GraphiQL is a built in tool to explore, build and run GraphQL queries in Turbot.

To open the explorer, login to your Turbot Workspace and click on Developers in the top right corner. GraphiQL

Run your first GraphQL query

Copy & paste this query into GraphiQL and click run:

{
  resources {
    items {
      title
    }
  }
}

The JSON results will match your requested format:

{
  "data": {
    "resources": {
      "items": [
        {
          "title": "my first resource"
        },
        {
          "title": "my second resource"
        }
      ]
    }
  }
}

Expand your query, observing autocomplete capabilities

Edit the query (resist the urge to copy & paste!) to request extra turbot metadata about the resources:

{
  resources {
    items {
      title
      turbot {        id        createTimestamp      }    }
  }
}

While you are editing the query above, you'll see autocompletion options appearing in the editor. Use this to try adding other fields to the results.

Discover inline documentation

In addition autocomplete, GraphQL comes with extensive inline documentation. Click the < Docs link in the top right hand corner to see an explore.

Search for the resources query in the documentation, you'll see it produces a list of the resource type [resource].

Clicking through to the resource type, you can see all the available fields.

Use filters to target your query

Add a filter to the resources query to target the results. In this case, we'll restrict results to the Turbot Profile resource type:

{
  resources(filter:"resourceType:profile") {    items {
      turbot {
        id
        createTimestamp
        title
      }
    }
  }
}

Find resources created in the last 6 hours:

{
  resources(filter:"createTimestamp:>=T-6h") {    items {
      turbot {
        id
        createTimestamp
        title
      }

    }
  }
}

Paging through results

Get the first page of results, including the next token. Notice the filter support for sorting and limiting results.

{
  resources(filter:"resourceType:profile sort:title limit:3") {    items {
      turbot {
        id
        createTimestamp
        title
      }
    }
    paging {      previous      next    }  }
}

The result includes paging metadata that can be used in the next request:

{
  "data": {
    "resources": {
      "items": [
        {
          "turbot": {
            "id": "162723451277834",
            "createTimestamp": "2019-06-19T10:33:40.387Z",
            "title": "Batman"
          }
        },
        {
          "turbot": {
            "id": "162723451277834",
            "createTimestamp": "2019-06-19T10:33:40.387Z",
            "title": "Danger Mouse"
          }
        },
        {
          "turbot": {
            "id": "162674901433086",
            "createTimestamp": "2019-06-18T21:23:28.429Z",
            "title": "Superman"
          }
        }
      ],
      "paging": {
        "previous": null
        "next": "eyJzb3J0IjpbeyJ0ZXh0IjoidGl0bGUifSx7InRleHQiOiJpZCIsIm9wZXJhdG9yIjoiLSJ9XSwid2hlcmUiOlt7InBpdm90IjoidGl0bGUiLCJvcGVyYXRvciI6Ij4iLCJ2YWx1ZSI6IkNodWNrIEdhbWJsZSJ9LHsicGl2b3QiOiJpZCIsIm9wZXJhdG9yIjoiPCIsInZhbHVlIjoiMTY1MDQyODYzMjU1MTk2In1dLCJtb2RlIjoibmV4dCJ9"      }
    }
  }
}

Query the second page of results by including the paging parameter. You have reached the end of the results set when next is returned as null.

{
  resources(filter:"resourceType:profile sort:title limit:3" paging:"eyJzb3J0IjpbeyJ0ZXh0IjoidGl0bGUifSx7InRleHQiOiJpZCIsIm9wZXJhdG9yIjoiLSJ9XSwid2hlcmUiOlt7InBpdm90IjoidGl0bGUiLCJvcGVyYXRvciI6Ij4iLCJ2YWx1ZSI6IkNodWNrIEdhbWJsZSJ9LHsicGl2b3QiOiJpZCIsIm9wZXJhdG9yIjoiPCIsInZhbHVlIjoiMTY1MDQyODYzMjU1MTk2In1dLCJtb2RlIjoibmV4dCJ9") {    items {
      turbot {
        id
        createTimestamp
        title
      }
    }
    paging {
      previous
      next
    }
  }
}

The final page of results will have a previous token, but next is null:

{
  "data": {
    "resources": {
      "items": [
        {
          "turbot": {
            "id": "164235079971230",
            "createTimestamp": "2019-07-06T12:37:00.283Z",
             "title": "Wonder Woman"
          }
        }
      ],
      "paging": {
        "previous": "eyJzb3J0IjpbeyJ0ZXh0IjoidGl0bGUifSx7InRleHQiOiJpZCIsIm9wZXJhdG9yIjoiLSJ9XSwid2hlcmUiOlt7InBpdm90IjoidGl0bGUiLCJvcGVyYXRvciI6IjwiLCJ2YWx1ZSI6IlJ1cGVzaCBQYXRpbCJ9LHsicGl2b3QiOiJpZCIsIm9wZXJhdG9yIjoiPiIsInZhbHVlIjoiMTYzMTQ1NDk2MDAyNTUxIn1dLCJtb2RlIjoicHJldmlvdXMifQ==",        "next": null      }
    }
  }
}

Mutations

Mutations allow modifications to existing Turbot resource metadata using GraphQL.

It is important to first start with a query to ensure the correct resource is being acted upon. Consider an example of updating an existing mod in Turbot using a GraphQL mutation.

Start with the query of all installed mods to get a list of the names and versions.

query InstalledMods {
  resources(filter: "resource:'tmod:@turbot/turbot#/' resourceType:tmod:@turbot/turbot#/resource/types/mod resourceTypeLevel:self sort:title limit:200") {
    items {
      akas
      version: get(path: "version")
    }
  }
}

An example response looks like the following:

{
  "data": {
    "resources": {
      "items": [
        {
          "akas": [
            "tmod:@turbot/aws"
          ],
          "version": "5.2.0"
        },
        {
          "akas": [
            "tmod:@turbot/aws-acm"
          ],
          "version": "5.2.2"
        },
        {
          "akas": [
            "tmod:@turbot/aws-amplify"
          ],
          "version": "5.0.1"
        },
        {
          "akas": [
            "tmod:@turbot/aws-apigateway"
          ],
          "version": "5.1.0"
        },
        {
          "akas": [
            "tmod:@turbot/aws-appstream"
          ],
          "version": "5.0.0-beta.4"
        },
        {
          "akas": [
            "tmod:@turbot/aws-athena"
          ],
          "version": "5.1.1"
        }
      ]
    }
  }
}

Suppose the tmod:@turbot/aws mod needs to be updated. This can be done by using the following GraphQL mutation.

mutation installMod {
  installMod(
    input: {
      parent: "tmod:@turbot/turbot#/" # AKA or ID for the turbot product
      org: "turbot" # Name of the organization to which mod belongs
      mod: "aws" # Name of the mod
      version: "5.3.0" # Desired version of mod
    }
  ) {
    turbot {
      id
    }
    data
  }
}

The as with other GraphQL queries, the response will be json.

{
  "data": {
    "installMod": {
      "turbot": {
        "id": "177146224838314"
      },
      "data": null
    }
  }
}

The id returned is the Turbot Id for the mod resource.

Mutations can also be used to create, change, or delete policy settings, update local user passwords, as well as creating various Turbot resources such as a smart folder.

Further Reading