Introduction to GraphQL
The API era
First of all, lets quickly have an idea about how an API works. In a typical REST API whenever you want to fetch data from your server you need to hit a specific endpoint i.e send an HTTP request to that endpoint. The basic idea behind an API is the resource that is identified by a URL. The resource gets retrieved by sending a GET request to that URL (endpoint). Let’s consider an example; consider you want to retrieve the data of users. In a RESTful environment, the API may look something like
GET /api/getUsers
Response:{
users [
user1 {
fname: ‘John’,
lname: ‘Doe’,
email: ‘john.doe@somemail.com’,
gender: ‘male’,
date_of_birth: ‘1-01-1991’,
contact: 1234455677,
.
.
}, user2 {
fname: ‘Jane’,
lname: ‘Doe’,
email: ‘jane.doe@somemail.com’,
gender: female,
date_of_birth: ‘2-02-1992’,
contact: 1232566677,
.
.
},
.
.
]
}
You get the JSON response which sometimes might be very big and shall contain some unnecessary data as well. In the following example, you get the data about all the users in your table stored along with all the information. Now let’s consider you want to get the posts published by a specific user with id 2, the API call would look something like
GET /user/id:2/postsWhich would then return all the information of the posts published by the user with id 2
This may seem fair but there may come a time and it will come when you only need some amount of data and not the entire chunk. This is where REST API’s start getting kind of annoying. For small pieces of data that you need on the frontend, you have to make so many API requests which in return has a larger payload.
This is where GraphQL becomes handy
What is GraphQL?
The official website says that GraphQL is a query language for your API.
GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
It was developed and open-sourced by Facebook and is now maintained by a large community of companies and individuals from all over the world. GraphQL is nothing but better implementation of RESTful APIs.
GraphQL is a declarative data fetching specification and query language for APIs. Declarative fetching is the type of fetching where the user can specify exactly what data it needs from the server and the server in return provides only the necessary requested data. In the case of typical API we may end up with multiple endpoints to retrieve the data, but with GraphQL we only have a single endpoint by which we access the data on the server. This single endpoint looks like:
/graphqlThis endpoint returns the response in the JSON format. GraphQL creates a uniform API across your entire application without being limited by any specific storage engine.
From the above example if we need only the id, first name and the email of the users then the simple SQL query will look like:
SELECT id, fname, email FROM users;Whereas a graphQL query looks something like this:
query {
users{
id
fname
email
}
}Output:
"data": {
"users": [
{
“id” : 1
"fname": "John Doe",
"email": "john.doe@somemail.com"
},
{
“id” : 2
"fname": "Jane Doe",
"email": "jane.doe@somemail.com"
},
.
.
]
}If you also want to show the projects of the users along with their project ids and names then the query will look like:
query {
users {
id
fname
projects {
id
name
}
}
}Output:
"data": {
"users": [
{
“id” : 1
"fname": "John Doe",
"email": "john.doe@somemail.com",
“projects”: [
{
“id”: 1,
“name”: “project 11”
},
{
“id”: 2,
“name”: “project 12”
},
]
},
{
“id” : 2
"fname": "Jane Doe",
"email": "jane.doe@somemail.com",
“projects”: [
{
“id”: 3,
“name”: “project 21”
},
{
“id”: 4,
“name”: “project 22”
},
]
},
.
.
]
}Each query consists of a set of fields with one root field and everything that follows the root field is called the payload. In the above query, the “users” field is the root field whereas the following fields are payload.
Queries, Mutations, and Subscriptions
- Queries, as the name says, are simple queries that are sent from the client which indicates what data is requested from the server.
- Mutations do the CUD operations such as: Creating new data, Updating the data & Deleting the data. Mutations follow the same syntactical structure as that of queries.
- Subscriptions are the way to get real-time updates from the server. This makes use of Websockets. Subscriptions are event-based in GraphQL.
GraphQL is a query specification for your API. Now if you have a query then you also need to have a schema. GraphQL APIs have a strongly typed schema which is the backbone of GraphQL APIs. The schema defines the operation such as queries, mutations, subscriptions that are to be performed on the data. These schemas are written using Schema Definition Language (SDL). This schema serves as the contract between the client and the server to define how a client can access the data.
Instead of having multiple endpoints that return fixed data structure, GraphQl APIs typically only expose a single endpoint. This works because the structure of the data that’s returned is not fixed. Instead, it’s completely flexible and lets the client decide what data is needed.
One major advantage of GraphQL is that it allows for naturally querying nested information.
Useful links
