Introduction
The word GraphQL keeps popping up a lot around the web. It has been mentioned in many technical events as well, the most recent being the AWS re:Invent 2017, where they announced AppSync, a fully managed GraphQL service.
Why is GraphQL suddenly making ripples in the developer community and how does its rise impact the tech world?
While the name can mislead you to believe it to be a query language, it is a replacement for REST (and its alternate versions). I have compiled the key takeaways for anyone who wants to understand GraphQL.
To help you better understand and highlight the differences, I have included illustrated examples using REST and HTTP.
What is GraphQL?
GraphQL was developed by Facebook internally in 2012 and was later released to the public in October 2015. In Facebook terminology: GraphQL is a query language designed to build client applications by providing an intuitive, flexible syntax and system for describing their data requirements and interactions. It provides a language to query data from backends and change data on them.
In a nutshell, GraphQL is a query language created by Facebook, that specifies how to ask data from APIs.
The Basics of GraphQL
GraphQL has 3 high-level operations:
- Queries - Used to fetch data, like
GET method in REST - Mutations - Used to create/modify data followed by fetch, like
POST, PUT, DELETE methods in REST - Subscriptions - Long Lived connections to receive updates on data from the server, like web sockets
These operations are exposed via a schema that defines the capabilities of an API. A schema is composed of types. The schema defined by the developer determines the capability of the GraphQL API.
Every GraphQL API can have two types:
- Root types, e.g., query, mutation, subscription
- User-defined types, e.g., todo, human, animal, etc.
Every GraphQL API will have a query type and may or may not have a mutation and subscription type. The root types determine the entry point of the GraphQL query.
Example query:
{
human(id: 101) {
name
age
}
}
The above query does the following:
- Starts with the
root object - We select the
human with id 101 field on that - For a
hero object returned, we select the name and age fields
The result of the query will be:
{
"data": {
"human": {
"name": "John Doe",
"age": 20
}
}
}
For the above query to work, we must add a human type to the schema which consists of the fields that it can return. The type of root query and human is as follows:
type Human {
name: String!
age: Int!
}
type Query {
human(id: ID!): Human
}
The fields of a type need to return some data. This happens in a GraphQL. API is through a concept known as a GraphQL resolver. This is a function that either calls out to a data source or invokes a trigger to return some value (such as an individual record or a list of records).
Resolvers can have many types of data sources, such as NoSQL databases, relational databases, or REST APIs. We can aggregate data from multiple data sources and return identical types, mixing and matching to meet your needs.
After a schema is connected to a resolver function, a client app can issue a GraphQL query or, optionally, a mutation or subscription. I am sure you have started to see how GraphQL is different from its predecessors and other commonly used databases.
However, does it have actual benefits? Let’s take a look.
Benefits of GraphQL
Better Data Retrieval
Querying data is very simple and round trips to the servers are reduced. Consider a blog that has content, comments, etc. Every comment can have description and users, every user will have name, email, list of blogs.
Imagine I need the blog contents with the comment, the user who commented and that user’s blogs. To achieve it, we will have to make the following REST calls.
GET - api/vi/blogs/101/ -> will return the blog with its contents
GET - api/v1/blogs/101/comments -> will return the comments of the blog
GET - api/v1/users/30/blogs -> will return the blogs of the user
Say we had 4 comments, hence N = 4 so the number of calls needed to be made are Step 1 + Step 2 + Step 3 x 4 which evaluates to 6 calls. We require the blogs of all the users who commented on the blog so step 3 will have to be performed multiple N times depending upon the number of users.
Now the exact same thing can be archived in 1 call when using GraphQL using the below query:
{
blog(id: 101) {
content
comments {
content
users {
name
email
blog {
content
}
}
}
}
}
Did you notice how we can replace several lines of code with just one simple logic?
Better Versioning
In a REST API, if there is a new field or some change in the resource, a new version of the endpoint must be created. This incurs managing more code, another endpoint and removing the old endpoint once deprecated.
GraphQL solves this problem by allowing the user to keep the same endpoint while adding new fields to the type dynamically without breaking any existing stuff.
Better Control of the Response Data
Consider we have an API that is consumed by a responsive web application. Depending upon the device where the app has opened, the data displayed on the screen will vary, some fields may be hidden on smaller screen devices and all the fields may be shown on devices with a larger screen.
The following infographic explains various pain points, pertaining to manage data returned when using REST:
With GraphQL, it’s just a matter of querying the fields that are required depending upon the device. The front end is in control of the data it requests, and the same principles can be utilized for any GraphQL API.
Aggregate Data
With GraphQL, we can easily aggregate data from different sources and serve it up to the users under a single umbrella rather than making multiple REST calls from the front end or back end. We can expose a legacy system through a unified API.
As mentioned above, every GraphQL API is composed of types, schema and resolvers. In order to create an API, we require to create a GraphQL server in some language. As you know by now, GraphQL is a language in its own and has a specification, the specification must be implemented in a programming language to be utilized.
Almost all modern programming languages now have an implementation of the GraphQL specification that you can utilize hence making integration and migration extremely smooth and easy.
Important Resources
As a programmer, I am sure you are eager to try out GraphQL. I have compiled some useful tools and libraries that you can utilize to make your journey with GraphQL more fun.
- graphql - An implementation of the GraphQL in JS
- Apollo - A toolkit for GraphQL. It has implementations of server for multiple platforms
- Prisma - A tool to turn your database into a GraphQL API. It supports multiple databases
- Scaphold - A hosted GraphQL backend
- AWS AppSync - A hosted GraphQL server that is fully managed AWS and connects to multiple data sources
Conclusion
GraphQL is very powerful and has a lot of potentials, but it is still in its infancy. However, in a short period of time, it has gained a lot of traction and has been widely adopted by the community.
The popularity clearly goes on to show the ease of use and the importance of GraphQL. The benefits that I have discussed here are just some of the ones that I have experienced while using it first-hand.
As the system evolves, I am sure a lot more would be unsurfaced - there is a huge ecosystem where GraphQL can be utilized.
See the complete video about GraphQL at https://youtu.be/vr2PiivOPZQ.
History
- 21st August, 2019: Initial version
