With GraphQL One Endpoint to Rule Them All


For developers who have been working with web API, if you have not heard of GraphQL, you may want to read on and plan to retire the REST (Representational State Transfer) API gradually and welcome GraphQL for fetching your data from a server.

Little History

GraphQL is an API technology that was initially developed by Facebook in 2012 for internal use, and it was moved from Facebook to the public in 2015 so other developers can take advantages. “At Facebook, our mission is to give people the power to build community and bring the world closer together,” said Killian Murphy, director of Facebook Open Source.“  In an effort to grow the GraphQL ecosystem, the GraphQL project was now moved to the newly-established GraphQL foundation, and on November 7, 2018, it is hosted by non-profit Linux Foundation and hope that it will be a widespread adoption and help to accelerate development of GraphQL and encourage participation and technical contribution.

What’s wrong with REST APIs

The REST API technology has become a dominant method of consuming APIs since it can be operated over HTTP easily more than a decade. It's a long time from an IT perspective. It has been worked great since it is a stateless protocol that separates the user interface concerns from the data storage. With the separation capabilities, it allows individual components to evolve independently, and eventually, it led to the development of microservices architecture. In the end, REST had helped us to achieve system scalability, shared cached, and security policies.

Nevertheless, as we began to develop more APIs to deliver good features to our users, we ended up with increased workload on tweaking existing API every time requirements have been changed. During the development process, we have created so many different APIs along the way and not to mention with other experimenting and versioning APIs because on one hand, we want to minimize making round trips from the client to the server to fetch data, and on the other hand, we want to minimize the size of response data and avoid fetching unnecessary data fields.  The orchestration of APIs becomes a management nightmare as developers were spending more time on deciding whether or not to use existing APIs or create new ones. Besides, more APIs means more round trips and more waiting time for users. As our projects become more complex, we require more requests from a server to get what we want. All these times added together to cause the degradation of performance of the applications as we add more new features to the applications. 

GraphQL comes to the rescue

Let’s try to compare how REST and GraphQL work analogous to a scenario of retrieving data from a SQL database.  In the REST world, there is no join or subquery or dynamic query, and we have to write multiple query statements back and forth to obtain what we want at the end. In the GraphQL world, we can write one dynamic query statement and request once for what we want.  Best of all, GraphQL allows us to custom our returned data just like a SQL query statement. So, it is truly one query for multiple purposes, and this is how it gets its name since GraphQL is a data query and manipulation language. It also looks just like JSON, and you can think of it as the JSON’s functions with a look of a typescript.

Here we show a declarative nature of GraphQL in its request and response syntax.

To request a search of a movie title here is an example of the query with a parameter called keywords:

  data(keywords: "panda"): {

The return response is shown here:

                 "data": {
                   "title": "Kung Fu Panda"
                   "description”: “The Dragon Warrior has to clash against the savage Tai Lung as China's fate hangs in the balance."
                   "movideId": "441773"


Here are the points why GraphQL shines:

1. GraphQL paid less attention to HTTP verbs

In GraphQL, you create a query-like statement that looks like a JSON-encoded body, and the HTTP verb is POST for most of the time, except, for introspection query, GET is used when it tries to query a GraphQL schema for details about itself. Other than these scenarios, there is no need to use other verbs like PUT or DELETE.

2. One GraphQL provides one multi-purpose endpoint

GraphQL only needs one endpoint to access data on a server, and unlike REST API, you need to make requests to multiple endpoints.  For example, in the REST API, you need to request detail information after you obtain a general result set from the first query. In GraphQL, you can obtain data from one request.

3. GraphQL does not have an over fetching issue

With the GraphQL, you can customize the fields of data you wish to return, so you don’t need to send unnecessary data out to the client since clients and servers are now decoupled.

4. GraphQL eliminates unnecessary API or almost-redundant APIs

Since there is only one endpoint for GraphQL, there is no needs to create other APIs and API management become simple.

5. GraphQL delivers a consistent data-mapping between client and server

Since GraphQL APIs' queries resemble the fields on the clients to the server since it is written clearly in the JSON-like query. This gives a consistent naming between the client and server sides and resolving issues can be minimized.

6. GraphQL is a declarative query language that is consistent with the UI development environment since the frontend programming is mainly declarative so it’s easy to work with data presentation. This is why GraphQL has a high adoption from the frontend developers.

7. GraphQL boots application performance

Without going to multiple round trips from clients to servers, single round trip is the King of performance comparing to other API technologies.

8. The GraphQL ecosystem is thriving

The Open source ecosystem of GraphQL has quickly become a mature community of supporting a variety of languages with various GraphQL clients, and tools to build GraphQL APIs.

GraphQL has delivered many great applications and has been used by many large companies, such as Twitter, Facebook, and Yelp. However, like any new technologies, there are still many challenges, and improvement lie ahead of the road. Currently, GraphQL has a total dependency on JSON’s development. Like any query database, there is a need to continue to optimize its query and efficiency. We are unsure how GraphQL takes care of handling errors, or issues rise coming from HTTP since at least for the past 17 years of REST/HTTP, we may have already figured what to do with REST/HTTP issues. Nevertheless, we are excited to see GraphQL become a thriving API technology, and we cannot wait to see how GraphQL transforms the landscape of the digital world.

If you have any thoughts about GraphQL or the article, I would love to hear what you have to say.  Thank you for reading.