There are two main ways to build APIs:
RESTful: (stands for Representational State Transfer, REST for short) At this point in time, is the most common choice among most devs. By virtue, they’re easy to implement, they’re stateless, and they return JSON data (although you could use XML as well).
GraphQL: On the other hand, is a query language that Facebook developed to make it easier for their mobile apps to query large amounts of data without making endless requests to the backend. It’s a potent and different approach from the RESTful way.
So which one of the two is a better choice for APIs?
Well, to answer this question, let’s look at the fundamental differences between the two, and we’ll also look at a real-life scenario. Let’s dig in!
1. RESTful APIs are Endpoint Based. GraphQL is Type Based
RESTful APIs deliver data via dedicated endpoints, and each endpoint might serve a different set of data. Essentially, the REST backend decides the returning data.
In contrast, GraphQL has a schema and is type defined. GraphQL displays all the schemas and types available for retrieval and allows you to get the data you really want.
2. HTTP calls
REST utilizes HTTP Semantics such as GET, POST, PUT, DELETE, etc., whereas GraphQL will always accept HTTP POST with a body consisting of the query.
3. Data Fetching
As REST only returns a specific dataset, we might have the case where we need to make several API calls to have all the data we need.
For that, we need to consolidate the result of several API calls. As we cannot choose the dataset, there will be cases of over-fetching or under-fetching, where we retrieve some unnecessary data.
Meanwhile with GraphQL, we are able to select the specific data so we will not have the same issue as REST API.
4. Swagger vs. GraphQL Explorer
Most of the time, REST APIs would include a web interface such as Swagger to allow developers to work on the endpoints and data. It will need more work on creating the swagger file and preparing the endpoints.
GraphQL offers a GraphQL explorer out of the box. The GraphQL explorer serves the same purpose as Swagger, and it allows developers to perform queries and retrieve data.
5. Versioning
REST will need versioning on the endpoints to return the new data schema and probably deprecate the old endpoints in the future.
However, GraphQL discourages versioning, or in a way, versioning is not necessary as the request for the data is explicit; it depends on how the consumer queries the data.
6. Managing Data
Most of the REST API separates the actions by HTTP Semantics like POST, PUT, DELETE. Meanwhile, GraphQL uses a query to retrieve data, mutation to edit or delete the data, and subscriptions to retrieve data from a long-lasting connection such as Web-Socket.
7. File Upload
REST supports file upload while GraphQL does not support file upload by default. However, GraphQL now has a third-party library that supports file uploads.
Real-Life Scenario
We are an e-commerce frontend application.
We are on the front page, where we need to show the user "Today's best deals" in a carousel image slide, followed by the "Free delivery Section" that lists all the items that are eligible for free shipping. The data we need for this would be the item's id, name, and the image URL.
With a REST API, we would have two ways of retrieving the data:
- For starters, we could get the data from 2 endpoints. One of the endpoints would be a "GET eCommerce/todayBestDeal" and another would be a "GET eCommerce/freeDelivery".
- The second method would be with a single endpoint that retrieves all the data at once, "GET eCommerce/frontPage."
In GraphQL,
- We will always connect to just one endpoint "example.com/api/graphql", passing in the query within the HTTP POST body to retrieve the data.
- We will also define the type for the data that enables retrieval.
type Items {
id: String!
name: String
imageURL: String
seller: Seller
}
type Seller {
id: String!
name: String
avatar: String
}
For this instance, we will pass in the query as such:
query {
product(isBestDeal:true, isFreeDelivery:true) {
id
name
imageURL
}
}
Both REST and GraphQL work fine.
Both serve the same data. Still can't see the difference, right?
Now, we take it a step further, we enhanced the frontend application to display even more information about the product, such as the seller info. We will now display the avatar of the seller, the name of the seller, and probably the seller ID too.
If we are using REST, we either retrieve the seller's data from another endpoint (e.g.: "/seller/:sellerId") or we would need to change the existing endpoint to return the extra columns.
- If we do that, this endpoint would no longer be reusable. It would only be serving one screen – the front page.
- If we are retrieving from the seller's endpoint, we’ll also be returning unnecessary data to the frontend regardless of whether it’s required or not (over fetching the data).
On the other hand, in GraphQL, with our data types setup previously, we only need to change the query to such:
query {
product(isBestDeal:true, isFreeDelivery:true) {
id
name
imageURL
seller {
id
name
avatar
}
}
}
GraphQL introduces a different approach from REST, and it is gaining popularity and it also has a growing community.
It definitely comes with a few advantages and also some notable limitations that you need to take into consideration before building out your backend.
In the meantime, you can play around with SpaceX’s GraphQL endpoint that’s open to the community.
