Working with GraphQL
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 are currently available for the following services
Before diving into writing queries, it’s important to understand some fundamental GraphQL concepts:
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 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 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.
Scalar types represent the basic, concrete data types in a GraphQL schema, such as String, Int, and Boolean.
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.
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.
Before using the GraphQL explorer, you’ll need your Tenant ID and an 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:
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.