GraphQL API

Use the CloudTruth GraphQL API to create flexible queries for configuration data. Perform create, read, update and delete operations on Parameters, Environments, Templates, and Integrations

Explorer

The CloudTruth GraphQL Explorer is an interactive IDE which runs in your browser. The Explorer is an instance of GraphiQL which which highlights available operations, fields, syntax, and errors. The Explorer can be used to run Queries and Mutations against your live CloudTruth configuration data.

Access the CloudTruth GraphQL explorer here:

https://explorer.cloudtruth.com/

Before attempting any operations, click the login button on the upper right. You will be redirected to the CloudTruth login screen, where you can login to your existing CloudTruth account, or create a new one. Once you've authenticated your account, you will be redirected back to the Explorer.

Queries

You can compose new queries by selecting items from the schema pane at the left. An example query for parameters by keyname is shown below.

{
viewer {
organization {
parameters {
nodes {
keyName
}
}
}
}
}

This query can be executed by pressing the run button at the top of the Explorer. The results for this query will be shown in the right pane of the explorer.

{
"data": {
"viewer": {
"organization": {
"parameters": {
"nodes": [
{
"keyName": "app.demo.color2"
},
{
"keyName": "app.demo.color3"
},
{
"keyName": "app.demo.color1"
},
{
"keyName": "app.demo.color0"
},
{
"keyName": "service.demo.timeout"
}
]
}
}
}
}
}

Mutations

You can compose new mutations by selecting items from the schema pane at the left. An example mutation for adding a new parameter is shown below.

mutation MyMutation {
__typename
createParameter(input: {keyName: "testParam", isSecret: false,
description: "sample", value: "123"})
}

This mutation can be executed by pressing the run button at the top of the Explorer. The results for this mutation will shown in the right pane of the explorer.

{
"data": {
"__typename": "Mutation",
"createParameter": {
"clientMutationId": null
}
}
}

Note that mutations will generally affect live configuration data. In this instance a new parameter is created.

Calling the GraphQL API

You can access the CloudTruth QraphQL API from a variety of languages and technologies. Multiple GraphQL clients are available, which are convenient for building queries, establish connections, authenticating, and parsing results.

In our first example, we've chosen to use Python, along with graphql-python/gql.

Authentication

In order to access the CloudTruth GraphQL API you will need an access token with the correct permissions. Follow the steps outlined in Managing Access Tokens to create a new access token.

Endpoint

The CloudTruth QraphQL API is available at a single endpoint:

https://ctcaas-graph.cloudtruth.com/graphql

Use this endpoint for all GraphQL operations.

Sample Code

The follow python example uses the graphql-python/gql client to:

1) Build a transport using the CloudTruth endpoint authorized with an access token, specified as the Bearer token below.

2) Create a GraphQL client

3) Create a GraphQL query

4) Execute the query

5) Parse the results as a Python dictionary

from gql import gql, Client
from gql.transport.aiohttp import AIOHTTPTransport
# Build a transport using a url endpoint
transport = AIOHTTPTransport(url='https://ctcaas-graph.cloudtruth.com/graphql',
headers = {'Authorization': 'Bearer CkGWYsXaFPR7zJHTpRwjccM8'})
# Create a GraphQL client using a transport
client = Client(transport=transport, fetch_schema_from_transport=True)
# create a GraphQL query
query = gql(
"""query {
viewer {
organization {
environments {
nodes {
name
}
}
}
}
}
"""
)
# Execute the query
result = client.execute(query)
# Parse the results
for key in result['viewer']['organization']['environments']['nodes']:
print(key['name'])