The GraphQL Way: Introduction (Part-1)

We find the solution when the problem is detected. Facebook found the solution to the problems of REST through the creation of GraphQL and now, it’s used by big companies like Github, Instagram, Shopify, Medium, and many more.

I’m going to talk about GraphQL and its implementation through a series of articles. In this first part, I will try to cover the following topics:

  1. What is API?
  2. REST and its pros and cons.
  3. GraphQL and its pros and cons.
  4. When should we use GraphQL?

What is API: API stands for Application Programming Interface and it acts as an intermediatory for two applications to exchange data. In fact, the moment you started reading this article, the browser is using a specific API to fetch the relevant content of the article from the server.

Since this is a way of exchanging data between applications, there should be some standards, right? Yes, SOAP, REST, GraphQL, and RPC are the most common standards for writing API. I’m not going to talk about all of these, wanna focus on REST and GraphQL.

REST: It’s an architectural style of writing API that stands for Representational State Transfer and was created by computer scientist Roy Fielding. One of the fundamental blocks of REST is resources. Every URL of REST API represents a particular state of the resource and defines what operation you can do with this resource. So, what is a resource?

Well, a resource is something that can be stored on a computer and represented as a stream of bits: a document, a row in a database, or the result of running an algorithm like a user, food, information about a car, etc.

RESTful APIs are stateless which means every request to the server is separate from each other.REST is language and platform agnostic which means information can be transferred in several formats like JSON, HTML, XML, Plain text, JPEG, and others.


  1. Easy to understand and implement.
  2. Decouple the client and server applications.
  3. HTTP cache support.
  4. Support multiple data transmission formats.
  5. Require lower bandwidth than SOAP.


1. Over-Fetching: It means there is data in the response of the API that isn’t actually used. Suppose, you have an API to display a list of books and the response contains the title, description, ISBN, and author. And all of these fields are used in your web application but when you decide to build the mobile app version of the web, you realize that you don’t need to display the description. In that case, the description is unnecessary which causes the extra bandwidth and it’s called over-fetching.

2. Under-Fetching: It is simply the opposite of over-fetching.In our previous use case, you also want to display the short profile of the author. So, you need another endpoint to accomplish that requires an extra HTTP round trip to the API server. And extra HTTP calls impact the performance of your application.

3. Less predictive and flexible.

GraphQL: It is a query language for APIs and a runtime for fulfilling those queries with your existing data. If I want to simplify the definition I would like to say, GraphQL enables the client-side application to query your APIs and take what exactly data it needs: no over-fetching or under-fetching. It’s completely language and platform agnostic and has nothing to do with your database layer like REST.

In GraphQL, data is represented through Schema and Type instead of resources. The schema defines what queries are allowed to be made, what types of data can be fetched, and the relationships between these types.

Suppose, Every author may have multiple published books and each book is published by only one author. In that case, our type will look like the below:

And now, If you want to display authors and their books, you can query like this:

You can also get only the authors by changing the query, don’t need to modify or add another API!

It’s really flexible and you can create a GraphQL schema and build an interface around it with any programming language.


  1. No over- and under-fetching: The client can request what exactly it needs, not more, not less, and also can fetch multiple resources at one HTTP call thus it solves multiple roundtrips to the server. It is very efficient where API needs to support different types of devices and high bandwidth internet connection is critical.
  2. Validation and type checking out-of-the-box: At the beginning, GraphQL validates the query that the client sends and checks if the request contains any forbidden fields. So, it reduces the development time and allows the developers to focus more on business logic.
  3. Autogenerated API documentation: GraphQL provides auto-generated documentation of your APIs and it keeps the documentation in sync whenever there is a change in the APIs and removes the complexity to maintain API versioning.
  4. Rapid application prototyping: GraphQL speeds up the development process by providing a single API endpoint that serves as a data proxy between the UI and the data storage. Client application developers get more flexibility and clear documentation that increase their productivity.


  1. Web caching complexity. REST APIs enable easy web caching configurations to match certain URL patterns, HTTP methods, or specific resources since it provides different endpoints for different resources. But GraphQL provides a single API endpoint for all data and it needs more work to enable caching.
  2. Performance: REST APIs are consistent over time because it sends the same resources from a specific endpoint but in GraphQL if the query contains too many nested data requests, it may affect the performance.
  3. Error handling: It is a bit more complicated to handle errors properly than REST APIs.

So, When should we use GraphQL?

Every API standard has its own limitations and neither one is the best fit in all use cases. As a developer or architect, you need to take this decision considering different factors.

  1. GraphQL can work well where bandwidth usage matters like a mobile, tablet, or IoT device.
  2. If your client application needs data from multiple data sources like legacy APIs, third-party APIs, and current APIs, you can combine them all in a single GraphQL service. It will be much more maintainable than REST.
  3. If you want to give more flexibility and gain rapid prototyping, you should go for GraphQL.

And that’s it for today!

In the following parts of the series, I’ll explore GraphQL theoretically and practically with Node.js, Express.js, Apollo GraphQL, Prisma, MySQL, and many more.

What are your thoughts? Let me know in the comments. Till then, Happy coding!

For more updates on this topic, you can follow me on Linkedin.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store