Particeep

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

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:

Request


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

Result


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

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

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

		            {
                "limit": 1
            }
        	
Result

		            {
                "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:

Step 4 - Use case

In order to use GraphQL to query our API, you will need to call the following endpoint:
(POST) /v0/graphql
And you need to pass a body containing :

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: `
                    query Users($limit: Int){
                        users(userSearchInputType: {}, table_searchSearchType: {limit:$limit}) {
                            data {
                                id
                                email
                                address {
                                    number
                                    street
                                    zip
                                    city
                                    country
                                }
                            }
                            total_size
                        }
                    }
                `
                variables: {
                    limit: 1
                }
            }
        	
Result

		            {
                "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:

Follow the next tutorial
If you are stil looking for informations not in this article, you can contact-us direclty