Modern users want to use their applications wherever it is convenient and on any gadget or device which are convenient for them. Therefore, the creators strive to make sure that their applications can be installed on all popular platforms: Android, iOS, macOS, Windows, Linux (mainly software created for the IT industry), and, of course, the web versions.
One of the first questions at the initial stage of development of any system is "What technology should be used to describe the API?" This question important to everyone, both the backend and the frontend.
REST (Representational State Transfer), created in 2000, has been a good option for communication for a long time. This paradigm is still actively used, it has huge community support and almost all backend frameworks offer it as a "default" solution. Therefore, I think every developer has heard about REST.
But technologies are evolving and more and more new development opportunities are opening up. GraphQL which was presented in 2015 by Facebook is one of these capabilities. However not everyone has heard about GraphQL, so today we will talk about the key differences between REST and GraphQL, and what should you choose for your project?
What is REST?
This API design style uses the required HTTP method (GET, POST, PATCH, PUT, DELETE) to exchange information. REST clearly defines the communication framework and expects the request and response to be of a specific type. In most cases, everyone's favorite JSON is used.
GET hostname/user/
This is an example of a typical GET request to get user data.
The answer will be in this format:
{
"id": 1,
"name": "Test name",
… other fields
}
It is important to mention that the server determines the structure of the response in REST architecture, not the client.
Pros of REST
- low entry threshold. Backend developers only need to read the guidelines and adhere to them, so the system can get the “RESTful” status. It is quite easy to find a new person to be added to the team who can quickly get started due to the low threshold and huge popularity.
- lack of coherence in teams. The application is divided into at least two teams (frontend and backend), which share responsibility. The frontend does not need to know what is happening on the backend part and does not depend on it. They only need endpoints that can be used to communicate.
- scalability. It is easy to extend the backend and add new logic if it is isolated from the frontend. That allows using versioning. So if we have different apps for few platforms and the one for Android has already rolled out an update, while one for iOS has not yet. So when accessing the API, the first application will communicate with the new version of the API while the last will communicate with the old one. Typically, the API URL looks like hostname/api/vN/endpoint, where vN is a version number - v1, v2, and so on.
Cons of REST
- excess data. Each application tries to display the user's page as similar to other platforms as possible. For example, in a web version, the full user profile is displayed on a large desktop screen but doesn’t fit on a small screen of a smartphone, so a short one should appear. So in the latter case, the server returns full, detailed information about the user, and mobile devices simply do not need it. And duplicating the endpoint for every case is not an option because someday a simple request to retrieve user data can grow to 10 options. And that will be difficult to maintain.
- lack of data. For example, you need to display a list of user’s friends. The User entity and the Friend entity are linked to each other in the database, but this cannot be used when using REST and it will be necessary to make two requests. One to get the user, another to get friends.
What is GraphQL?
GraphQL also is used to design APIs, but everything is referred to as a graph of interconnected data. It has only one endpoint, (usually /graphql). It means that you can get all the data and if necessary entity relationships from a single point.
In practice, the graph consists of three main building blocks: schema, queries, resolvers.
Resolvers
They are needed to receive a request on the server, process incoming arguments, and form a response
Schema
- Indicates different endpoints.
- Defines input and output fields for an endpoint.
- Defines the action to be performed when the endpoint is reached, and so on.
Resolvers and schemas are described by backend developers.
Queries
API requests are very similar to the exact direction to the personal assistant, that is, the most detailed description of the directions. For example, “go to my office, there is a red folder on the table, find document number 2 on the 30th page of the sheet in the folder”. GraphQL is very similar, the example below shows this (go to the server and grab all the posts and their authors).
query {
posts { # it’s array
title
body
author { # model User
name
avatarUrl
profileUrl
# any available field
}
}
}
The chain of nesting can go on for a very long time until all fields become of a scalar type.
And the response will be returned strictly in the same format.
{
"posts": [
{
"title": "Post title 1",
"body": "Body 1",
"author": {
"name": "Test name",
"avatarUrl": "link",
"profileUrl": "link",
}
},
# other posts
]
}
As you can see in the column, everything is clear which response format will be returned from the server.
Pros of GraphQL:
- you get what you asked. No redundant or scarce data.
- easy implementation on the client-side. For example, all you need to get a new field if it appears in our user profile is to add it to Query. You don’t need to disturb the backend team (they have already done their job).
Cons of GraphQL:
- high entry threshold. Many developers are familiar with REST but have no experience with GraphQL. It makes it difficult to find a new teammate.
- absence of automatic caching. GraphQL uses only one endpoint. It does not allow the HTTP caching specification to be followed. But this problem is perfectly solved by client wrappers for GraphQL (Apollo Client, Relay).
- error handling difficulties. The request always returns status 200 even if it is wrong. It makes development more difficult.
And one more piece of advice. GraphQL should not be used for small systems such as a dashboard, blog, or personal webpage. REST can handle such tasks easily.
Summary
Briefly analyzing both approaches, I think it is clear that REST has some important drawbacks, which, in turn, are solved by GraphQL. But I recommend you to take into account all the features of the two technologies and be very careful when choosing them for your project.
