Executing GraphQL Queries (Legacy)

This guide shows how to execute GraphQL queries and mutations against Exacta Maestro™'s schema.

Warning

This content is for Exacta Maestro™ customers whose projects went live prior to 2022. New customers should review Executing GraphQL Queries

Endpoints

Exacta Maestro™'s GraphQL schema is exposed over HTTP through Bastian Solutions's load balancer. The address varies per customer, but the schema is consistently accessed with three paths:

http://{load-balancer-address}/{clientId}/{environmentId}/graphql
http://{load-balancer-address}/{clientId}/{environmentId}/ui/playground
http://{load-balancer-address}/{clientId}/{environmentId}/graphiql

The /graphql path is for posting queries to the GraphQL schema. It is the primary endpoint for production workflows. The /ui/playground and /graphiql endpoints are for administrative use. They provide a schema explorer and query editor to test arbitrary queries.

The values for load-balancer-address, clientId, and environmentId will be distributed during system setup. Note that clientId and environmentId are case-sensitive.

Example Query

The samples in this guide all use the following GraphQL query and variables. It creates a task group with Exacta Maestro™'s Task Assignment service.

# Query

mutation createTaskGroupOperation($input:TaskGroupInput!) {
  taskAssignmentMutation {
    createTaskGroup(createTaskGroupInput:$input) {
      id
      name
      dateCreated
      taskGroupState
    }
  }
}

# Variables

{
   "input": {
    "name": "My Task Group"
  }
}

Raw HTTP Request

GraphQL Requests are made with an HTTP POST. These headers are required:

Host: http://{load-balancer-address}/graphql Content-Type: application/json

The POST body is a JSON object with the following structure:

{
    "Query" :"",
    "OperationName": "",
    "Variables": {}
}

Query: The full text of the GraphQL query to execute. Since GraphQL is a language of its own, this is a string rather than a JSON object.
OperationName: The name of the operation to execute. This can be omitted if the query contains a single operation.
Variables: A JSON object containing any variables defined in the query's operation. The keys in the root of this object will be the variable names. The variable values will be scalars or objects mapping to the GraphQL type defined for the variable. If no variables were declared in the operation, this field can be omitted.

Here is an example of a raw POST to create a Task Group in Exacta Maestro™. This example was created in PostMan and traced with Fiddler.

POST http://localhost:81/graphql HTTP/1.1
Host: localhost:81
Connection: keep-alive
Content-Length: 315
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36
Cache-Control: no-cache
Origin: chrome-extension://fhbjgbiflinjbdggehcddcbncdddomop
Postman-Token: f64c72c1-54c3-9374-d698-8a8d3d489c6e
Content-Type: application/json
Accept: */*
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9

{
	"Query": "mutation createTaskGroupOperation($input:TaskGroupInput!) { taskAssignmentMutation { createTaskGroup(createTaskGroupInput:$input) { id  name dateCreated taskGroupState } } }",
	"OperationName": "createTaskGroupOperation",
	"Variables": {
      "input": {
        "name": "My Task Group"
      }
    }
}

With the UI Playground

Visit http://{load-balancer-address}/ui/playground. The displayed page contains an editor where you can type your query with intellisense support. Click the play button at the UI's top center to execute the query. Click the 'Schema' button to explore the available operations and types.

With Powershell

GraphQL requests can be made with Windows Powershell v3 and higher using the Invoke-RestMethod cmdlet.

$body = @{
  query = @'
mutation createTaskGroupOperation($input:TaskGroupInput!) {
  taskAssignmentMutation {
    createTaskGroup(createTaskGroupInput:$input) {
      id
      name
      dateCreated
      taskGroupState
    }
  }
}
'@
  operationName = "createTaskGroupOperation"
  variables = @{
    input = @{
      name = "My Task Group"
    }
  }
}

$jsonBody = ConvertTo-Json $body -Depth 10

$result = Invoke-RestMethod -Method 'Post' -Uri $GraphQLConfig.uri -Body $jsonBody -ContentType "application/json"

With C#

You can use .NET's HttpClient class to post a GraphQL query. HttpClient is available since .NET 4.5 and in all editions of .NET Core. This example also uses the NewtonSoft.Json library to serialize the request and deserialize the response.


using Newtonsoft.Json;
using System;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace HttpClientTest
{
    class Program
    {
        static readonly HttpClient httpClient = new HttpClient();

        static async Task Main(string[] args)
        {
            var body = new
            {
                Query = @"mutation createTaskGroupOperation($input:TaskGroupInput!) {
                             taskAssignmentMutation {
                               createTaskGroup(createTaskGroupInput:$input) {
                                 id
                                 name
                                 dateCreated
                                 taskGroupState
                               }
                             }
                           }",
                OperationName = "createTaskGroupOperation",
                Variables = new
                {
                    input = new
                    {
                        name = "My Task Group 2"
                    }
                }
            };

            var jsonBody = JsonConvert.SerializeObject(body);
            var stringContent = new StringContent(jsonBody,
                                                  Encoding.UTF8,
                                                  "application/json");


            using(var httpResponse = await httpClient.PostAsync("http://localhost:81/graphql",
                                                                stringContent))
            {
                if(httpResponse.StatusCode == HttpStatusCode.OK)
                {
                    var responseBody = await httpResponse.Content.ReadAsStringAsync();
                    dynamic graphQLResponse = JsonConvert.DeserializeObject(responseBody);
                    var taskGroupId = graphQLResponse.data.taskAssignmentMutation.createTaskGroup.id;
                    Console.WriteLine(taskGroupId.ToString());
                }
            }
        }
    }
}