Hello, in this post I would be talking about GraphQL. According to Wikipedia GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data.
Now, this might sound ambiguous but let me try to make it simple by comparing it to something most of you reading this post is knowledgeable about.
Recall that in a POST request, you can attach some data in the body of the request. For instance, a POST request using the fetch API might look like this below:
Now a GraphQL request is not really different from a POST request. The difference is that rather than the usual JSON object to be used in the body of the POST request, a GraphQL query in JSON format is used. For instance below is a function that uses GraphQL to fetch the data of authors.
In the code above you’ll notice that a graphql request looks a little bit similar to using REST to make a request.
Some of the things you would notice are:
- A POST request method was used to fetch data instead of a GET method
- The stringified data looks a little bit different from a regular JSON object
So the reason why a POST request is used is that by standard a POST request allows the appending the data to the body. The body is where the GraphQL query is attached. Once the query is sent to the server, the GraphQL runtime tries to interpret what the query is asking for and sends it back to the client or front end.
For you to make use of a GraphQL endpoint you’ll need to learn how to write a GraphQL query. Lucky enough it isn’t that difficult to understand.
Before I continue, one thing you also need to understand is that a GraphQL endpoint responds using a regular JSON object.
There are two important things to know in GraphQL:-
- The Schema
- The Query Language
The Schema defines what can be requested for from the GraphQL server. And the Query defines what you want to fetch from the server.
The Schema defines the data that can be obtained from a query in a typed manner. Below is an example of the type I chose to define in my query
Looking at the Query type in the schema above we can see that there are two fields that can be returned from a Query which are “books” and “authors”.
The authors field can return either an empty array or an array of Author types.
The books field can return either an empty array or an array of Books types.
The Book type can only return the id, title or author of the book and the Author type can only return the id, name and an array of books written by an author.
You can’t write a query that contains fields that are not defined in the schema. For instance, writing the query below using the schema defined above would return an error because the location field was not defined in the schema.
Generally, the ecosystem of REST isn’t used with its standardization in the majority of client code written.
The GET method is mostly misused to take on the actions of other methods.
For instance, you might see cases where a DELETE method should be used to perform a deletion request but instead the GET method is used.
I’ve done that as well a lot. lol….
In GraphQL, there is something called MUTATION.
Just as the name implies, a Mutation is a type of query that is performed by your client when you want to initiate any form of change in your server.
A change can include: deleting, updating or creating.
The code written above is what a Mutation query looks like for creating a book. I also added the schema for the mutation and the Book type in the code. just to get a clear picture.
GraphQL query types ( Query, Mutation, Subscription) allows you to attach parameters which makes them look like javascript functions. The parameters are like variables that you can use to send new data or fetch specific data to or from the server.
In the mutation above, the parameters for adding a book are: “title” and “author”
If you look properly in the code you’ll see that the mutation query only requested to fetch the “title” field after the mutation once the mutation is completed.
That’s the beauty of GraphQL. It makes data fetching to be totally declarative. The mutation schema above shows that the createBook Mutation can only return a Book type. And a Book type contains various fields. But the query only wants the title field to be retrieved.
You only get what you ask for. Unlike in REST, when you try to consume an API endpoint you are more likely to fetch more than what is needed and this makes the client consume more data than needed across the network. In fact when this was one of the main bottlenecks that Facebook faced which made them come up with the idea of GraphQL.
To add to the benefits of GraphQL, there is support for real-life updates. So that means you can use GraphQL for a chat application. This is made possible by what is called Subscriptions.
At this point, you might be asking your self if you need different endpoints to use a GraphQL setup. And the answer is no. This is also one of the benefits of GraphQL. You only need a single endpoint and various queries to perform different things.
When it comes to documentation, this comes off easily in GraphQL, there is something called introspection in GraphQL. In introspection, the client can query the GraphQL endpoint to know the possible fields it can query. An extra bonus is that not only can the client see the possible fields, but it can also see the type of the field eg. String, Array, Integer etc.
Using the fetch API to perform a GraphQL query might seem tedious and that’s true. The good news is that there are some very cool libraries out there that makes GraphQL handling to be easy. The one I would recommend to use is Apollographql. The documentation is well written and I’ve also contributed to it.
One other thing you need to know is that you don’t need to scrape out your existing code infrastructure to support a GraphQL setup. GraphQL allows you to create a separate endpoint that manages all the GraphQL request which is awesome. Due to this, it integrates well with old infrastructures and can also be used monolithically for both old and new infrastructures.
GraphQL also has its issues but I believe that it has brought more good to the table.
Below are various resources you can use to get started with graphql.
If you have any comment to make please do leave it down in the comment section below. Thanks a lot
