GraphQL — The end of serializers
Has it ever happened to you that while developing an API, the response ended up being a very large json with a few nested objects?
On the one hand, that is useful because you get the complete response in one request. On the other hand, if you only require a small portion of it, it is inefficient because generally, including a nested object implies slower database queries, mainly because of the use of JOIN statements.
This also requires the use of serializers to build the json response for both for the main object and for the nested so that we can build the complete json.
This is where GraphQL jumps in, because it is a query language that uses a schema to describe the shape of the data graph and it enables to ask only for the data you need.
Could you give me an example?
If you have not used GraphQL before, I recommend that you read this documentation and checkout this library.
Suppose we are using a relational database in which we have a table of companies:
And we have another table of employees:
We would like to make two queries, one requesting all company fields including its employees, and the other one requesting a few fields with no association.
So, we would define two types: one for the company ( GraphQLCompany) and another one for the employees (GraphQLEmployee).
How do we make the request to our API?
We could create a GraphQL query that fetches a company with all their attributes as seen below:
We could have another query that only fetches a company with some of their attributes. In this case, by not fetching the employees, the additional query is not performed.
We can either make an HTTP POST request to our API using this query as the body, or use a client library such as Apollo client which makes it easier.
Let’s implement the GraphQL query
We define the getCompanyById query which acts as a controller in our API. This GraphQL query has a resolve function that receives an id as an argument and returns a GraphQLCompany type
We can see that that we have a repository object to access the database and fetch the company and return a company model in the resolve function of the query. We do not serialize the response because the GraphQLCompanytype is the one in charge of serialization, by accessing the fields of the returned object.
How to define a GraphQL type?
When we define a query in our API, we specify the type of the response, so the object that the query returns should respect the type definition. Each field in the type definition matches with the object that is returned.
So in the case of the employees, an additional query is required. In that case we use the custom field resolvers. These are functions that are executed if the field is requested in the query, allowing us to perform the additional query to the database only when it’s needed.
Let’s define the company GraphQL type where we specify its attributes:
We see that we have a Company model we define with our Object-Relational mapping (ORM) and each field is a column in the model, but where are the employees? We know that in order to get the association we have to perform additional queries to the database, but only when the field is requested, so that is where the field resolvers jump in.
Let’s define the employee GraphQL type first:
Then we can add the employees field to the Company type.
Finally, we see that the Company model from our ORM has an association with the Employee model where we can perform the additional query with a simple company.getEmployees()method and the operation is only performed if the field is requested, because the resolve function will only be executed if the field is part of the query that our API receives.
Conclusion
These are just some of the guidelines that I learned from my experience using GraphQL. At first I made the classic mistake of designing my custom serializer to use in the response of each query or mutation until I understood the purpose of the strong typing that GraphQL gives us.
Now it’s your turn and experience the journey of GraphQL!
