GraphQL vs. REST: What have you learned?

Overview

When creating a web service application, you can choose to use REST or GraphQL as the communication mode. Both may use JSON over HTTP, but have different advantages and disadvantages.

This article mainly compares GraphQL and REST to operate a product database example, comparing the differences between the two solutions when performing the same client-side operations:

• Create a product in draft state
• Update product details
• Get product list
• Get detailed information about a single product and its order

REST

The main data element of REST (Representational State Transfer) is called Resource. In this case, the resource is "Product".

• Create a product

 curl --request POST 'http://localhost:8081/product' \
 --header 'Content-Type: application/json' \
 --data '{
 "name" : "Watch" ,
 "description" : "Special Swiss Watch" ,
 "status" : "Draft" ,
 "currency" : "USD" ,
 "price" : null ,
 "imageUrls" : null ,
 "videoUrls" : null ,
 "stock" : null ,
 "averageRating" : null
 } '

• Update Products

 curl --request PUT 'http://localhost:8081/product/{product-id}' \
 --header 'Content-Type: application/json' \
 --data '{
 "name" : "Watch" ,
 "description" : "Special Swiss Watch" ,
 "status" : "Draft" ,
 "currency" : "USD" ,
 "price" : 1200.0 ,
 "imageUrls" : [
 "https://graphqlvsrest.com/imageurl/product-id"
 ] ,
 "videoUrls" : [
 "https://graphqlvsrest.com/videourl/product-id"
 ] ,
 "stock" : 10 ,
 "averageRating" : 0.0
 } '

• Get product list

 curl --request GET 'http://localhost:8081/product?size=10&page=0' 

 {
 "id" : 1 ,
 "name" : "T-Shirt" ,
 "description" : "Special beach T-Shirt" ,
 "status" : Published ,
 "currency" : "USD" ,
 "price" : 30.0 ,
 "imageUrls" : [ "https://graphqlvsrest.com/imageurl/1" ] ,
 "videoUrls" : [ "https://graphqlvsrest.com/videourl/1" ] ,
 "stock" : 10 ,
 "averageRating" : 3.5
 }

• Get a single product by order

To get a product and its orders, you typically need to first call the product list API and then call the order resource to find the related orders:

 curl --request GET 'localhost:8081/order?product-id=1' 

 {
 "id" : 1 ,
 "productId" : 1 ,
 "customerId" : "de68a771-2fcc-4e6b-a05d-e30a8dd0d756" ,
 "status" : "Delivered" ,
 "address" : "43-F 12th Street" ,
 "creationDate" : "Mon Jan 17 01:00:18 GST 2022"
 }

In addition to the original operation of getting all products, this operation needs to be performed once for each product of interest, which creates an N+1 dependency problem.

GraphQL

GraphQL API operations include Queries and Mutations. Queries are responsible for obtaining data, and Mutations are used to create and update.

The Schema mode of Queries and Mutations defines the possible requests and responses of the client.

• Create a product

 curl --request POST 'http://localhost:8081/graphql' \
 --header 'Content-Type: application/json' \
 --data \
 '{
 "query": "mutation {saveProduct (
 product: {
 name: \"Bed-Side Lamp\",
 price: 24.0,
 status: \"Draft\",
 currency: \"USD\"
 }){ id name currency price status}
 }"
 }' 

 {
 "data" : {
 "saveProduct" : {
 "id" : "12" ,
 "name" : "Bed-Side Lamp" ,
 "currency" : "USD" ,
 "price" : 24.0 ,
 "status" : "Draft"
 }
 }
 }

• Update Products

 curl --request POST 'http://localhost:8081/graphql' \
 --header 'Content-Type: application/json' \
 --data \
 '{"query": "mutation {updateProduct(
 id: 11
 product: {
 price: 14.0,
 status: \"Publish\"
 }){ id name currency price status }
 }","variables":{}}' 

 {
 "data" : {
 "updateProduct" : {
 "id" : "12" ,
 "name" : "Bed-Side Lamp" ,
 "currency" : "USD" ,
 "price" : 14.0 ,
 "status" : "Published"
 }
 }
 }

• Get product list

 curl --request POST 'http://localhost:8081/graphql' \
 --header 'Content-Type: application/json' \
 --data \
 '{
 "query": "query {products(size:10,page:0){id name status}}"
 }' 

 {
 "data" : {
 "products" : [
 {
 "id" : "1" ,
 "name" : "T-Shirt" ,
 "status" : "Published"
 } ,
 ...
 ]
 }
 }

• Get a single product by order

 curl --request POST 'http://localhost:8081/graphql' \
 --header 'Content-Type: application/json' \
 --data \
 '{
 "query": "query {product(id:1){ id name orders{customerId address status creationDate}}}"
 }' 

 {
 "data" : {
 "product" : {
 "id" : "1" ,
 "name" : "T-Shirt" ,
 "orders" : [
 {
 "customerId" : "de68a771-2fcc-4e6b-a05d-e30a8dd0d756" ,
 "status" : "Delivered" ,
 "address" : "43-F 12th Street" ,
 "creationDate" : "Mon Jan 17 01:00:18 GST 2022"
 } ,
 ...
 ]
 }
 }
 }

GraphQL Advantages

GraphQL allows for flexible and dynamic queries:

• The client can only request fields defined in the Schema
• Support aliases for requesting fields with custom key values
• Clients can use queries to manage the order in which results are returned.
• Clients are better decoupled from any changes in the API

GraphQL tends to avoid expensive operations, and you can usually get all the data you need in a single request using GraphQL.

When to use REST

GraphQL is not a replacement for REST. REST might be more appropriate in the following cases:

• Applications are resource-driven, where operations are directly and completely tied to individual resource entities.
• Web caching is required because GraphQL does not natively support it
• File upload is required because GraphQL does not natively support

in conclusion

The choice of using REST or GraphQL as the communication mode needs to be determined by the business scenario. The flexibility of GraphQL also determines its complexity to a certain extent.

When using GraphQL, you also need to consider cache optimization at the application level and batch operation optimization to solve the N+1 problem.