Building a Simple GraphQL Query
Integrations GraphQL Training Simple GraphQL Query

Building a Simple GraphQL Query

The GraphQL Operations

Everything that hits a GraphQL web service is commonly called a GraphQL “query”. But this terminology is somewhat misleading. The 4me GraphQL schema includes two Operations or Root Types: the Query type for reading data and the Mutation type for changing data.

A Simple Query

Now let’s have a look into the basic anatomy of a GraphQL query string to perform a simple query type operation.

In the first place you specify the Operation or Root type query. Next you can give a name to your query (optional).

As we have already explained the graph in GraphQL is based on the idea of a space that consists of a graph of nodes or objects. But where to start ? That’s defined in the GraphQL schema: the schema defines the possible entry points in the object space. Most of the time you will start your query with a list of 4me records, like ‘Requests’ or ‘Configuration Items’ that are available in the 4me account that you have specified in the header.

Apart from these collections of records (we will call them root level connections and discuss them in more detail in the next chapter), there are a few simple fields that can act as your entry point for your GraphQL query: these fields are documented on this page.

One of these entry points is me. ‘me’ is the currently authenticated person. In fact me is an instance of the object Person (like Bobby is an instance of the object Dog). On the developer site this is defined as :

me (Person!)

The exclamation mark after Person means that the field is non-nullable, i.e. the 4me GraphQL service promises to always give you a value when you query this field.

You need to specify the field you want to query, in this case me, in curly brackets.
But that’s not enough. One of the advantages of GraphQL is that it lets you retrieve exactly the data you need and nothing more. That’s great, but this all means that you must tell GraphQL exactly which data you want to retrieve. In this example, you cannot ask the 4me GraphQL service to just return every data of me, you will need to be more specific. That’s what you will define in the Selection Set. The Selection Set consists of the fields you want in the query response and these fields must also be enclosed in two curly brackets.


Anatomy of a simple query

So the next question you need to answer is which fields are available for a Person object. You can find them on this page of the 4me developer site. And, that’s what GraphQL introspection has to offer, this information is readily available in Insomnia: just place your cursor after me { and hit CTRL-Space to get the list of fields that are available on the me object.

Get the available fields for a GraphQL object in Insomnia with CTRL+Space.

In this list of available fields you can find the name and the unique id of the person record. Now you have all the info to create your first GraphQL query.

Exercise:

Check the body of this GraphQL query in Insomnia:
Query the me object with GraphQL


There are many more fields available for a Person object . In the list of available fields you will find a manager (which is again an instance of the object Person.
manager (Person)

Questions:

The manager field is not a manadatory field on a person record: this field is nullable.

The GraphQL query will return an error in the response: field 'manager' returns Person but has no selections
Query the manager of the me object with a wrong Selection Set


You know by now that a field is set to nullable in the 4me GraphQL API when the field is not mandatory. But this is not true the other way around: when a field is mandatory, it doesn't mean that it is set to non-nullable by default. The reason is that your integration's personal access token might not have access rights to the field. And when the integration does not have access rights the 4me GraphQL API will return null. And what if the integration's personal access token doesn't have access rights to all the fields of a related object? An example is the Requested for user on a Request. This person can be defined in a 4me account for which your integration user has no access rights. In such a case, when you query the details of an associated object that you are not permitted to see, the 4me GraphQL API will only return the id, name and account of that object.

The GraphQL Tree and his Leaves

Now let’s try to understand why the 4me GraphQL API gave an error when you specified the manager field in the Selection Set of me. Again, this is due to the fact that you must tell GraphQL exactly which data you want to retrieve.

To understand the rule that applies here, it is important to understand GraphQL types. Basically in a GraphQL schema one can define any object type one needs. For all these objects the available fields must be defined, and in their turn these fields can also be an object type. But at some point those fields that belong to an object have to resolve to some concrete data.
Knowing that GraphQL is independent of any specific programming language, it can’t rely on a specific programming language syntax. Therefore GraphQL has defined some basic types that every programming language is able to understand. These basic types are called scalar types.
GraphQL comes with a set of default scalar types :

When you specify a field in a GraphQL query, you always need to specify an associated Selection Set, except when the field is a scalar type! When the objects or nodes in a GraphQL space are represented as a tree, the scalar type fields are the leaves of the query, these fields don’t have any sub-fields. The rules is that a branch in a query should always stop on a leaf. For the me object this looks like:

The graph of the me object including the leaves

Exercise:

Don’t forget to add read rights on the person, organization and account record types to the scope of the personal access token.
In Insomnia, this query looks like:
Query the account of the organization of my manager with GraphQL


Next Topic