By: Dr. Shailesh Kumar Shivakumar, Solution Architect

Graphs are traditionally used for establishing relationships between entities, modeling hierarchies, or traversing a path. However, graphs can also be used for APIs through GraphQL to reduce the number of API calls. In this blog, I illustrate how this can be done and outline the advantages of GraphQL compared to traditional REST APIs.

GraphQL for APIs

REST (Representational State Transfer) is one of the most popular architectural styles for designing modern APIs. REST identifies the noun/resource and provides verbs (such as GET, POST, DELETE, PUT) to modify the state of the resource. We use REST over the existing HTTPS protocol, and JSON is used as the payload format.

For example, GET api/v1/products lists all the products and POST api/v1/products/1234 updates the product with id 1234.

Most modern web pages and views need to aggregate data from several sources. Let’s consider a product dashboard page that shows the product image, along with a brief description and the product download link. As the product image and product brief descriptions are used on other views, we will most likely create separate granular REST APIs for fetching product images and product brief descriptions. This leads to calling three REST APIs as shown below:

To reduce the number of API calls, we can create a product façade or a product aggregator in the server to fetch all the information. Alternatively, we can also invoke three calls in parallel asynchronously to further optimize the performance.

However, in some cases (such as traversing a product hierarchy and listing the product details for the selected product) where the product details service has a strict dependency on the product id fetched from the selected product, we cannot invoke two calls at the same time. If the information is obtained from various data sources, we will have to aggregate the information through all those sources. We can overcome this problem using GraphQL.

In GraphQL, the primary entities are nodes, and the relationship to other nodes is presented by the edge. In GraphQL, each object has a structured schema using GraphQL Schema Definition Language (SDL) that acts as the contract between the view and the GraphQL API. GraphQL engine uses a resolver to get the details for each node.

For the product dashboard page we discussed earlier, we can use a single GraphQL API with this schema:

GraphQL exposes a single API endpoint and internally retrieves the data from the required sources.

REST vs. GraphQL

Here are the key differences between REST and GraphQL:

Use cases for GraphQL

• If the application frequently needs information modeled in hierarchies and relationships, then GraphQL is better suited to these requirements. Social media platforms and map traversal apps are some of the examples where GraphQL will be most useful.
• When we would like to create a single API endpoint for both mobile and web applications, GraphQL will be effective. Based on the criteria, mobile can query only the required information from the single GraphQL endpoint.
• REST APIs are mature and provide a robust error-handling model (such as HTTP response codes), security, and caching mechanism. Hence, applications that benefit from caching can leverage REST APIs.

Thus, GraphQL is often the ideal choice as it reduces the number of API calls and can handle multiple resources more efficiently. However, REST APIs may be used in select cases where their capabilities are suited to the scenario’s requirements.