Using REST is a must-do for API building, today. GraphQL allows another interesting way to display content.
What is GraphQL?
GraphQL is easily understandable, more than a standard to connect data, it is a whole world of good practices that should be followed (or not…). When intergrating third-party services, we expect to get a REST API with its own entry point used to call for HTTP GET / POST and so on… With its own results sent using the JSON format.
GraphQL is simple but there are a few cons. GaphQL is an another enterprise solution that allows to solve some pitfalls of the REST architecture. GraphQL doesn’t aim to kill REST, according to its creators, they’re considering that both can be used depending on the project’s needs. By now, we can’t state if one will make the other obsolete.
Many businesses (such as Facebook and Github) are already using it in production. Github provides an extra in addition of its REST API : a GraphQL version.
Why do we use GraphQL?
Let’s state that we have an API allowing us to retrieve some content from a blog. We would use a GET /post/{id} method on one hand that retrieves the last blog posts published or even a specific post. On the other hand, we would use a GET /comment/{id} method to get comments of a specific blog post.
We want to display the last 3 blog posts on the website’s front page . And other posts from the same author on the post detail page.
If we’re lucky enough, the API could provide parameters like «?limit=3 » to only get the last 3 blog posts or even «?author=’’xxx’’ » to filter posts by author, but that’s not mandatory. We have to read the documentation (if it exists), then, we have to check out the running API version to know how the parameter’s structure is made.
At this stage, the front-end dev team can be in charge of the client-side processing but that’s not necessary as the data-team can work on it too. The question is: should the data team work on it even if the task is related to content display? The database used to store blog posts is well structured, we know that each blog post is made of: an author, a title, commentaries.
What if you only want to display titles in the homepage? If the GET /post_title method exists, everything should be perfect. If not, you’ll need to retrieve all the data only to display the title.
That’s not a big deal, we’re all doing it all the time and even if we ask the browser to retrieve 100kb of data only to display 10 %, we don’t really care because of our high speed unlimited internet connection. So, we are all doing it, but that’s definitely not the best thing to do.
The next morning, someone is asking you to display comments on the front page after each blog post. Once again, unless someone added the information in a GET /post method, you’ll have to send an additional HTTP request to retrieve comments and their number for each post retrieved. That‘s a common practice, but it can be really hurtful with poor internet connections.
What if we want to rename or add a field in our API? With an architecture, it implies that we have to maintain two versions of a single API to avoid problems for user using the first version of the API.
The goal of GraphQL is to bring a solution to solve all these situations (wobbly most of the time).
GraphQL is a request langage (QL for « Query Language ») initially developed by Facebook (when a company is aiming to dominate the market in emerging countries, each request and each kb is important).
GraphQL offers a better separation of responsibilities between display logic and business logic.
GraphQL is working between the client (not the one who pays you) who needs specific information and your server that have to provide it.
GraphQL allows :
- To only get the requested information (and only the information needed)
- To create nested requests (for example: gettingblog posts and each blog post’s commentaries in a row)
- To get an « automatic » documentation that deals with the data’s structure we can get. GraphQL forecasts it and tools are available to know results structure to choose what kind of information we would like to render, relation between them and so on.
- To be version independent. As we get what we requested, when a field isn’t used anymore, we can deprecate it to warn the technical team, but the information remains available for the needed duration.
GraphQL, how does it work?
With GraphQL, there is not only one endpoint used for all our requests. For example :
{
author {
name posts {
title comments {
comment
}
}
}
}
Here’s what will be returned
{
"data":{
"author":{
"name":"C. Dugué",
"posts":[
{
"title":"Drupal 8.4 est là !",
"comments":[
{
"comment":"Ça fait plaisir !"
}
]
},
{
"title":"Nouveau site Bluedrop",
"comments":[
{
"comment":"C'est pas trop tôt ! ;)"
}
]
}
]
}
}
}With a single request, we got structured information (and only the requested information, not more, not less).
With REST we would create multiple requests to get the author id, then an another to get blog post linked to author’s id and for other blog post: other requests to get the right comments…
Here’s a request allowing to get the comments’ number with their page number :
The request :
{ hero { name friendsConnection(first:2 after:"Y3Vyc29yMQ==" ) { totalCount edges { node { name } cursor } pageInfo { endCursor hasNextPage } } } }
We will get :
{ "data":{ "hero":{ "name":"R2-D2", "friendsConnection":{ "totalCount":3, "edges":[ { "node":{ "name":"Han Solo" }, "cursor":"Y3Vyc29yMg==" }, { "node":{ "name":"Leia Organa" }, "cursor":"Y3Vyc29yMw==" } ], "pageInfo":{ "endCursor":"Y3Vyc29yMw==", "hasNextPage":false } } } } }
What about Drupal?
There is a GraphQL module for Drupal allowing to expose CMS’s content with the appropriate endpoint.
Tools are available to render these data,. One of them is developed by Facebook and is named Appolo. It provides necessary libraries (React, Angular, Swift) for requests and client-side rendering. There is also an adaptation of this library for VueJS available here.
Do we have to kick REST ?
Not yet… And even not at all. Once again both technologies are made to get along with each other. One of the current GraphQL’s limit is the caching management system, harder to setup than REST.
For easy projects with high traffic, the current system is still a good choice.
Ludovic Coullet - @lcoullet
Official website : http://graphql.org/
Useful ressources:
