GraphQL is an open-source query language used to deliver data to mobile and web applications. Unlike most traditional REST APIs, GraphQL APIs only have a single endpoint to retrieve all the required data for your app.
Facebook developed GraphQL in 2012, and it has continued to grow in popularity since. The biggest strengths of GraphQL include the ability to control exactly what information you receive from the server and receive data in a predictable structure, and the ability to request data from multiple sources in a single request.
GraphQL can replace more traditional RESTful APIs. A RESTful API architecture strongly ties the type of resource to the method used to retrieve it, so there is a separate endpoint to request each resource type. In other words, you have less control over exactly what data you are fetching because the object structure is hardcoded into the server. This requires you to over-fetch data in many situations.
For example, we might want to fetch data about a company and its founder from an API. If we wanted to retrieve only the company name, company location, and founder name using REST, we would have to make two separate queries to retrieve all the data we need. The first request would be to GET /company, which would retrieve all the information stored about a company. In response to the first request, there would be a founder_id, which is then passed to the GET /founder request. Again, the second request would return all the data associated with the founder.
If the only information required was the company name, company location, and founder name, then time and resources were wasted fetching the additional data. With GraphQL, we can simplify this quite a lot. The first step is to define the schema of our API. The schema for a GraphQL API defines a structure for how the data — populated from back-end data stores — is formatted and nested.
Then, as part of the request to GraphQL, we can decide exactly what data our applications require from this schema. For our example, we only need the company name, company location, and founder name. This is the structure of our query and response. Using GraphQL allows us to request data from multiple resources with one query instead of many. Since we only requested the company name, company location, and founder name, that is the only data returned. All the other data (company location, founder Twitter, etc.) is excluded since we did not specifically request it.
The way data is requested from an API is one of the fundamental differences between REST and GraphQL. With GraphQL, we don’t need to make multiple round trips to fetch data. With a single request to the server, we can retrieve all the initial data required for the user’s entire session.
GraphQL also makes API users less dependent on the server. This means the server does not need to hardcode the size or shape of data, allowing the users to select what data they should get when they make a particular API call.
Since Facebook invented GraphQL, it is no surprise that it continues to be a popular choice for social networking sites. Facebook, Twitter, Instagram, and Pinterest all reported using GraphQL in their stack. Other companies that have explained their choice to use GraphQL include Airbnb and the New York Times.
After our research, we decided to use GraphQL instead of a RESTful API gateway because GraphQL provided a flexible solution and matched our application’s needs. As GraphQL continues to become more popular, it is important to remember that it isn’t the right solution for every situation. We hope this breakdown of our decision-making process and implementation helps illustrate how you can decide for yourself if GraphQL or RESTful API gateways are better for your project.
Written by Ilya Vinokurov, Director of Engineering at RapidAPI
