An Introduction to GraphQL
By: Apoorv Bhargava
Tags: GraphQL, API, Software Engineering, Integration, Rest

Application programming interfaces (APIs) enable the developers to build efficient applications allowing software to speak to each other and to conversate via requests most of which are Representational state transfer (REST) APIs. Over the last decade, REST produces stable and reliable APIs thus becoming the standard of today. Operations done with REST require many HTTP endpoints that return fixed data structures which can easily result in excess data.

GraphQL was designed precisely for the need for more flexibility and efficiency in client-server communication. GraphQL uses types and fields to describe data and schemas. Queries to API result in precise, predictable results without anything excess. This is done by exposing only one HTTP endpoint because of a very flexible data structure.

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

A comparison with REST

Let’s see a simple use case to illustrate the major differences between REST and GraphQL when it comes to fetching data from an API.

In a travel blogging application, an app needs to display the titles of the posts of a specific user. The same screen also displays the names of the last 3 destinations travel by the specific user.

REST API would typically gather the data by accessing multiple endpoints. In the example, these could be:

1. /users/{id} endpoint to fetch the initial user data.

2. /users/{id}/posts endpoint that returns all the posts for a user.

3. /users/{id}/destinations that return a list of traveled destinations per user.

In GraphQL, you’d simply send a single query to the GraphQL server that includes the specific data requirements. The server then responds with a JSON object to realize the solution.

What problems does GraphQL solve?

Prevents over or under-fetching: REST responses often contain too much or too little data thus creating the need for another request. GraphQL solves this efficiency problem by fetching the specific and cumulative data in a single request.

Rapid Product Iterations on the Frontend: With every change that is made to the UI, there is a high risk that now there is more (or less) data required than before. One of the most obvious benefits is that less code is required to perform frontend functions. Moreover, it is easier to understand because developers can analyze the object and know what to expect the API to return. This results in a faster project turnaround for both the frontend and backend teams.

Customizing requests to your needs: As it was mentioned, REST API documentation explains individual endpoints, their functions, and the parameters a developer can pass to them. Describing the data types, fields, and the interaction points between them, GraphQL API enables developers to tailor the request to get the information they need.

No need to maintain API versioning: REST API documentation explains individual endpoints, their functions, and the parameters a developer can pass to them. Describing the data types, fields, and the interaction points between them, GraphQL API enables developers to tailor the request to get the information they need.

Other advantages include but are not limited to Insightful Analytics on the Backend, autogenerating API documentation, strong schema, and type system, subscriptions, etc.

What are some disadvantages?

Although GraphQL is a decent alternative to REST, it’s not a replacement yet. This is due to some limitations, for instance:

Caching complexity: A REST API enables easy web caching configurations, by providing many endpoints, to match certain URL patterns, HTTP methods, or specific resources. Due to having only one endpoint with many different queries, it’s complex to use this type of caching with a GraphQL API.

File uploading: Since GraphQL doesn’t understand files, a file uploading feature is not included in its specification.

Complex queries and performance issues: When it comes to accessing multiple fields with one query whether it is requested in a RESTful architecture or GraphQL, the varied resources and fields still have to be retrieved from a data source. So, it also shows the same problems when a client requests too many nested field data at a single time.

Resource driven apps: REST can be also a valuable approach for connecting resource-driven apps that don’t need the flexible queries offered by GraphQL.

Conclusion

In comparison, between REST APIs and GraphQL, there’re unique interaction scenarios in which one or the other fits better.

In situations when a requester needs the data in a specific format for a specific use, data formats and the relations between them are vitally important GraphQL provides an elegant and efficient solution.

Analyzing all the tradeoffs that go into each design style such as — use cases, programming languages, architectural landscape, environment, financial implications — architects and API designers can pick the one that’s going to fit the project best.