Concepts
Working with GraphQL

11min
Overview
GraphQL is a powerful query language for APIs and provides a more efficient and flexible alternative to traditional REST API. GraphQL allows developers to request the data they need, leading to more efficient and precise data retrieval. This guide introduces GraphQL’s basic concepts, including terminology, structuring queries, and using a GraphQL explorer to interact with its APIs.
GraphQL Schemas
GraphQL schemas are currently available for the following services
﻿dispatch﻿﻿
﻿order﻿﻿
﻿workflow﻿﻿
﻿container﻿﻿
Terminology
Before diving into writing queries, it’s important to understand some fundamental GraphQL concepts:
Schema
A schema defines the shape of your data. It serves as a contract between the client and server, specifying the data structure and relationships that can be queried or modified.
Fields
Fields are the properties of an object that you can query. For example, in a query requesting user information, the fields might include name, age, and address`. Fields can also be nested, allowing you to request data on related objects within a single query.
Arguments
Arguments allow you to pass variables to fields, enabling you to request specific data based on your requirements. For example, you might request a specific user by providing a user id as an argument.
Scalars
Scalar types represent the basic, concrete data types in a GraphQL schema, such as String, Int, and Boolean.
Connections
Connections enable you to paginate and filter related objects by querying a GraphQL API. Connections are particularly useful when dealing with large sets of related data.
Using a GraphQL Explorer
A GraphQL explorer is an interactive tool that helps you build and test GraphQL queries. It provides features like auto-completion, syntax highlighting, and real-time error checking to make the process of writing and executing queries more efficient. There are several GraphQL explorers available, such as GraphiQL, GraphQL playground, and Apollo Studio.
Credentials
Before using the GraphQL explorer, you’ll need your Tenant ID and an access token.
Tenant ID: Follow the Getting started using Platform Credentials guide to get your Tenant ID.
Access Token: Call the Client Credentials grant token endpoint to retrieve your access token.
Follow the steps below to build and test queries in a GraphQL explorer:
Open your preferred GraphQL explorer.
Use {tenant}.base/api/v2/core/api/v1/graphql/grapqhl endpoint for queries.
Start writing your queries in the editor.
The example query below retrieves information about a specific dispatch, using the provided tenant and dispatch ID. To obtain the tenant and dispatchID arguments, we used the following API calls:
tenant: GET https://{base_url}/core/api/v2/participants/tenants﻿
dispatchId:  POST https://{base_url}/core/api/v1/dispatch-service/dispatches﻿
Query
GraphQL
query {
  dispatch(tenant: "os1devs", dispatchId: "dispatch:7abd9d35-8d2b-43c3-bf15-22fc3a9febe8") {
    createdAt
    createdBy
    customData
  }
}
query {
  dispatch(tenant: "os1devs", dispatchId: "dispatch:7abd9d35-8d2b-43c3-bf15-22fc3a9febe8") {
    createdAt
    createdBy
    customData
  }
}
﻿
In this query,  dispatch is the root of the query field that accepts tenant and dispatchId as arguments. We also included the createdAt, createdBy, and customData fields to be returned for the dispatch object.
Result
JSON
{
  "data": {
    "dispatch": {
      "id": "dispatch:a0ab6199-14d6-4973-a91e-26618ab9e52b",
      "createdAt": 1681878835466,
      "createdBy": {
        "id": "id",
        "name": "name",
        "appId": "app:1d6ebc25-32df-4dfc-b93b-4af5750dff37"
      }
    }
  }
}
{
  "data": {
    "dispatch": {
      "id": "dispatch:a0ab6199-14d6-4973-a91e-26618ab9e52b",
      "createdAt": 1681878835466,
      "createdBy": {
        "id": "id",
        "name": "name",
        "appId": "app:1d6ebc25-32df-4dfc-b93b-4af5750dff37"
      }
    }
  }
}
﻿
﻿