Flexible query with graphQL

In this page you will learn in 10 minutes how to use GraphQL in order to make queries to Particeep's API.
GraphQL is a query language that isn't tied to any specific database or storage engine and is instead backed by our code. A GraphQL query is a simple string that is sent to the server to be interpreted, and which will return JSON back to the client. It is a language designed to provide a flexible way to fetch any data.

Step 1 - Why using GraphQL instead of REST ?

Here are some points that makes GraphQL interesting

• GraphQL is faster than REST because as you can select the fields you want to query, the request will always be the smallest possible. And because less bits will be transferred over the wire so your pages will load faster.
• With GraphQL you can query multiple entities in one request (like getting the manager of an enterprise for example), so you will use less quota included in your subscription.

Step 2 - Getting started

First, let's see what a simple GraphQL query to our API looks like, and then we will cover step by step each part of the query:

		        {
            users(userSearchInputType: {}, table_searchSearchType: {limit:1}){
                data{
                    id
                    email
                }
                total_size
            }
        }
        	

		        {
            "data": {
                "users": {
                "data": [
                    {
                        "id": "b5d37e61-31e2-4dc3-a008-947f045b8b45",
                        "email": "klaxuz.apps@gmail.com"
                    }
                ],
                "total_size": 24
                }
            }
        }
        	

• The first thing to write in our query is the entity that we want to fetch, in this case we are fetching users
• The second thing to write is the parameter(s) of the query, in this case the query takes 2 parameters : userSearchInputType, and table_searchSearchType, both of them are objects, and they can be empty.
• Finally, the last thing to write is the list of the fields that we want to get on the entity, in this case, the result will be a paginated sequence containing an array of users object, and some other properties (like total_size). And the id and email specified in the data object tells to GraphQL that we only want to fetch these 2 properties for each users of the result.

Step 3 - Variables

In the previous example, we wrote our arguments inside the query string, but in real applications, the arguments have to be dynamic. In order to do this, GraphQL offers you the possibility to use variables. They have to be defined at the top of the query, and the value of these variables are provided along with the request containing the query. By doing so, our endpoint will be able to build the query.
Let's see what the previous query looks like with variables:

		            query Users($limit: Int){
                users(userSearchInputType: {}, table_searchSearchType: {limit:$limit}) {
                    data {
                        id
                        email
                    }
                    total_size
                }
            }
        	

		            {
                "limit": 1
            }
        	

		            {
                "data": {
                    "users": {
                    "data": [
                        {
                            "id": "b5d37e61-31e2-4dc3-a008-947f045b8b45",
                            "email": "klaxuz.apps@gmail.com"
                        }
                    ],
                    "total_size": 24
                    }
                }
            }
        	

There are 2 differences between this request and the previous one:

• The keyword query and the operation name have been added to the beginning of the query, it's helpful to make the code less ambiguous. You also have to do this if you want to pass dynamic variables
• The arguments inside the query string have been replaced by the variables we setted.

Step 4 - Use case

• query : A string containing the query (Required)
• operationName: A string containing the operation name (Optional)
• variables: Object containing the variables (Optional)

So the call to the endpoint will contain a JSON body like this:

		    {
        query: `
            query Users($limit: Int){
                users(userSearchInputType: {}, table_searchSearchType: {limit:$limit}) {
                    data {
                        id
                        email
                    }
                    total_size
                }
            }
        `
        variables: {
            limit: 1
        }
    }
	

NB: I don't display the result here because it is the same as the previous request in the Step 2.

Step 5 - Going further: Schemas

In the previous steps, we saw how to query our users table but we did not cover one important thing that makes GraphQL excellent: Schemas. But first, let's do a quick recap: a GraphQL query is basically about selecting fields on objects, that makes the result predictable without knowing that much about the server. But it can be useful to know what fields we can ask for, what kind of object they return, and that's where schema comes in. Every GraphQL query defines a set of types which describes the data we can query on that service, then when queries come in, they are validated and executed according to that schema.

Now, let's see a real example in our API. The users table contains a field called address_id, and in our schema, we have replaced this field by an address field that is an object containing the address of the user instead of a simple foreign key. And generally we do this for every foreign key on our GraphQL schemas. So, always with our users query, we can now fetch users including the address of each user

		            {
                query: `
                    query Users($limit: Int){
                        users(userSearchInputType: {}, table_searchSearchType: {limit:$limit}) {
                            data {
                                id
                                email
                                address {
                                    number
                                    street
                                    zip
                                    city
                                    country
                                }
                            }
                            total_size
                        }
                    }
                `
                variables: {
                    limit: 1
                }
            }
        	

		            {
                "data": {
                    "users": {
                        "data": [
                            {
                            "id": "b5d37e61-31e2-4dc3-a008-947f045b8b45",
                            "email": "john.doe@gmail.com",
                            "address": {
                                "number": "100",
                                "street": "Rue Petit",
                                "zip": "75019",
                                "city": "Paris",
                                "country": "FR"
                            }
                        ],
                        "total_size": 24
                    }
                }
            }
        	

Step 5 - Next steps

Now you know how to use GraphQL to query Particeep's API,you may want to look at the full GraphQL documentation: