In this article let us explore GraphQL. Let us first understand what GraphQL is? GraphQL is a specification from Facebook. GraphQL is a query language for APIs and runtime for fulfilling those queries with your existing data. GraphQL gives clients the power to ask for exactly what they need and nothing more by avoiding over fetching or under fetching of data. We can understand it more when we are going to see GraphQL implementation in action. Till then hold your curiosity.
Wait, Wait… So far we are using REST(Representation State Transfer) to expose our services as APIs. Let us ask some questions ourselves before getting deeper into GraphQL.
Why do I need to adopt GraphQL?
What problems am I facing with REST APIs? How GraphQL solves those?
To answer the above queries let us take a use case to build an e-commerce application for web, mobile and native clients. We decided to expose APIs for various e-commerce functionalities. For example, I have product detail REST API which gives specific product information as JSON which includes product data attributes, specifications data, reviews data, etc. As we are having many attributes in product JSON, the size of it is more. Each client (web and thin clients(mobile and tablets)) has it’s own front end requirements to display product data as they have different screen sizes, memory, network bandwidth, etc. Now my clients started consuming product detail API. Though mobile and tablet interfaces don’t require entire product JSON as web, still product detail API is giving entire product data. It is evident that clients don’t have control over the data what they want from the server. This is called over fetching. The pictorial representation of REST over fetching issue is given below.
We can solve over fetching issue with various approaches. The straight forward approach is to maintain different APIs for thick and thin clients. Though this design solves over fetching issue but has other problems like code maintenance, implementation of enhancements across different APIs, deployment of thick, thin client APIs, more compute, more manpower, etc., which puts more cost to project. The other approach is having middleware to intercept the client request. Based on client request filter the response to return. This adds an additional layer to the application which has the same issues as the previous approach.
Now let us discuss the second issue with REST called under fetching. To avoid over fetching, we decided to create granular APIs so that clients will make API calls for whichever the data they required. Let us take a product detail page for the web. It has product information, specifications and reviews to display. Now to render product detail page client is not going to get data in a single API call. So client needs to make multiple API calls (like basic product API, specification API, Reviews API) to cater to its data requirement. This design has performance issues with an increased number of round trips to the backend server and APIGateway. The other issue is requiring more computing power and network as rising in the number of requests to serve. Below is a pictorial representation of under fetching.
Let us see the third issue with REST that is, evolving APIs with versions. Any API will evolve as business needs will change with time. As per our customer needs, we might need to add data attributes(most of the cases we won’t remove data attributes as we need to have backward compatibility) to existing APIs. When we do any changes to existing APIs, we need extra vigilant as the changes might break the clients. To avoid that we will do versioning of APIs as and when we plan to release changes to existing APIs. When we introduce new versions which put the burden of managing more APIs(i.e. more compute power, more manpower), planning to deprecate older versions. Discipline and communication are needed when we have more versions of an API. With REST we cannot do silent releases.
The above issues are leading us to look for another solution called GraphQL. We will see how GraphQL addresses the above-said issues by implementing an API in the upcoming article. Meanwhile, let us see the request and response paradigm with GraphQL and how GraphQL makes clients happy by serving what they want.
Here are some of the adopters of GraphQL https://graphql.org/users/.
In the coming article, we will see the implementation of an API with GraphQL. Till then Spread love for APIs!!!
Siva Janapati is an Architect with experience in building Cloud Native Microservices architectures, Reactive Systems, Large scale distributed systems, and Serverless Systems. Siva has hands-on in architecture, design, and implementation of scalable systems using Cloud, Java, Go lang, Apache Kafka, Apache Solr, Spring, Spring Boot, Lightbend reactive tech stack, APIGEE edge & on-premise and other open-source, proprietary technologies. Expertise working with and building RESTful, GraphQL APIs. He has successfully delivered multiple applications in retail, telco, and financial services domains. He manages the GitHub(https://github.com/2013techsmarts) where he put the source code of his work related to his blog posts.
Smart Techie 
Couldn’t you implement a client based response filtering at the API Gateway level if you are already using one? What advantage you get from GraphSQL in that case?
Putting logic at APIGateway level or building middleware(I think we did this approach for our implementations) to filter response based on client has issues like manageability of code(I mentioned this in my article) . Even if you put logic at Gateway level clients doesn’t have freedom to get what they want from server. For example I am building API for mobile native clients. Different customers are using my API to build applications. In that case each customer’s data requirement is different. But still I give same data for all customers. This over fetching data issue has been addressed by GraphQL. GraphQL gives freedom to clients to query what data they want from server. In the coming article I will show you how it works.
Thanks Siva for the explanation