Web development would be hard to imagine - if there were no APIs.
What API is to web is what waiter is to restaurant. There’s the user (customer) and there’s the software (cook) but how the data or information (food) will be transferred to these two will be only handled by waiter (say API). APIs are all about connection or a way to integrate data from one source to another source.
In web development, generally APIs are supposed to be RESTful. The connection of an app with REST API works like this: a request is sent to a specific URL, and the results are received in the form of XML, JSON, HTML, plain text, JPEG, PDF or whatever format is suitable as per application.
However, Facebook comes with a new way to define APIs with GraphQL. In this article, we will put together a comparison between REST and GraphQL. We will learn what these technologies are and how they are different from each other. As an addition, we will also look at some use-case where these two API development technologies should be used.
What is REST?
REST is an API design architecture used to implement web services. It is one of the ways to send data over HTTP.
Before diving into what makes an API RESTful and what constraints and rules you should follow. Let us explain the two key terms: Client and Resources.
The client is the software or person who uses API. It can be a developer, for instance, being a developer, you can use Twitter API to read and write data from Twitter. Also, you can create a new tweet and do more actions in a code, which you write. Your code will call Twitter’s API.
The client can be a web browser. When you visit the Twitter website, your browser is the client who calls Twitter API. It uses the returned data to render information on the screen.
A resource is an object with a type, associated data, and relationships to other resources, and a set of methods that operate on it. In other words, a resource can be any object the API can provide information about. For example, Instagram’s API, a resource can be a user, a photo or a hashtag. Each resource has a unique identifier. The identifier can be a name or a number.
Now, let’s back to understand REST.
The RESTful web app exposes information about itself in the form of information about its resources. It also allows clients to take actions on those resources like create new resources (create a new user) or change existing resources (i.e. edit a post).
You have to follow a set of constraints in order for your APIs to be RESTful. The REST set of constraints will make your APIs easier to use discover. It means when a developer who is starting to use your APIs will have an easier time to learn how to do so.
As we’ve already stated, REST stands for Representational State Transfer. When a RESTful API is called, the server will transfer to the client a representation of the state of the requested resource.
Let's take an example: when a developer calls Instagram API to fetch a specific user (resource), the API will return the state of that user, including their name, the number of posts, which user posted on Instagram so far, and how many followers they have. The representation of the state can be in a JSON format. It can also be in XML or HTML format.
What the server does when you, the client, call one of its APIs, which depends on two things, which you need to provide to the server:
1. An identifier is a URL for the resource, also known as the endpoint. In fact, URL stands for Uniform Resource Locator.
2. The operation you want the server to perform on that resource, in the form of an HTTP method, or verb. One of the most common methods are GET, POST, PUT, and DELETE.
For instance, fetching a particular Twitter use by using Twitter’s RESTful API, will require a URL that identifies that the user and the HTTP method GET.
What is GraphQL?
GraphQL is a query language for API. It is all about data communication. Suppose, if you have a client and a server and both of them need to talk with each other. The client needs to tell the server what the data it needs and the server needs to fulfill this client’s data requirements with actual data. GraphQL steps into the middle of this communication. The question is why can’t the client just communicate directly with the user? It sure can.
Considering GraphQL as alayer between clients and servers, there are a few reasons: one of those reasons, and the most popular one is - efficiency. In general, the client needs to ask the server about many resources and the server usually understands how to reply with a single resource. Therefore, the client ends up doing multiple round-trips to the server to gather all the data it needs.
With GraphQL, we can shift this multi-request complexity to the server-side and have the GraphQL layer deal with. The client asks the GraphQL layer a single question and gets a single response. This is exactly what the client needs.
There are a number of benefits to using a GraphQL layer, for example, one other big benefit is communicating with multiple services. If you are having multiple clients requesting data from multiple services, a GraphQL layer in the middle can simplify and standardise this communication. Though, this is not really a point against REST APIs as it is easy to accomplish the same over there. However, a GraphQL run-time offers a structured and standardised method of achieving it.
Rather than the client going to be two different data services directly, we can have the client communication with GraphQL layer. The GraphQL Layer will do the communication with two different data services. This way, GraphQL isolates clients from needing to communicate in multiple languages. It also translates a single request into multiple requests to multiple services using different languages.
REST VS GraphQL: The Difference
By using GraphQl, you generally end up with a much better API comparatively if you would attempt to build a REST API without understanding its concepts. After all, the lack of REST knowledge resulted in the boom of the so-called REST APIs. I am sure you know the problems associated with the REST API. All these problems are the reason for GraphQL existence. It makes complete sense. GraphQL might be the better way to go only when -
1) The time is the essence
2) Your API is a disposable service
3) Only one client that you control consumes your API
4) You can’t afford to study REST or to learn HTTP in-depth
5) You can’t hire someone with the expertise to help you
Far too much, I would rather see GraphQL APIs than so-called REST API, which does not even understand the HTTP protocol. I am tired of trying to figure out which ID to put to which URL, or what is the difference between v2 and v3, or why do I have to use the POST HTTP method with a colossal request body to perform what is safe, idempotent and cacheable operation.
I do understand that there are people who don’t have time to study REST or learn HTTP. And, while we can question whether they should be the ones to build APIs, with GraphQL there is a solution for them.
True REST API is hard to pull off. It takes educated clients to consume the API correctly. If you have decided to go with the micro-services architecture, REST is probably the best style in order to enable for independent evolution of services and context separation.
It almost feels like REST and micro-services architecture were meant for each other. It also took me years to fully understand the REST, the mechanics and benefits of the server-driven application state interaction, accordance - centric design and the reality of frameworks & implementations. Depending upon where you are in your API journey making a quick judgement on what you think REST is. It might lead to the world of problems known as so-called REST API.
So-called REST APIs
There are a lot of variants of so-called REST APIs. The APIs do not follow all the required REST constraints but still dare to label themselves as REST APIs.
In this category, the best you can hope for is an API, which honors the HTTP protocol and follows its semantics. Such APIs generally are called as “HTTP APIs”.
A good HTTP API renders all the benefits of the existing internet infrastructure but it still tightly couples clients with servers making an independent evolution a chore. It still requires a significant amount of understanding of the protocol on both producer and consumer parts.
You can’t fix it if your HTTP knowledge is not the strongest. It also might be a better idea to act as there is no network at all and to use GraphQL comparatively create an immature so-called REST API.
Selecting GraphQL allows you an easy to design and amazing to consume API. It also rewards you with effortless consistency between the APIs. By its nature, GraphQL is contact-driven and comes with introspection that is something REST lacks out-of-the-box.
Using GraphQL leaves you vulnerable to what HTTP protocol and the whole internet infrastructure already solved like -
3) Network communication mechanics
4) Concepts like content and language negotiation
Some of these can be “added” to a GraphQL API but are not included in-the-box. By adding the functionality that comes with HTTP leads to bike-shedding. Unfortunately, these home-made solutions ruin the genius of consistency between GraphQL APIs.
Pros and Cons
1) High performance, especially over HTTP2
2) Proven for decades
3) Works with any representation
5) Server-driven application state
6) Full decoupling of client and server enabling the independent evolution
9) It embraces multiple APIs or dedicated resources for specific client needs.
10) No reference documentation needed
1) It comes with a huge entry barrier in training and learning, which most of us never overcome.
2) It requires clients to play along
3) No framework or tooling guidance
4) Poor or no tooling for clients
5) Requires discipline on all sides
6) You have to be an expert and then you still would not get it right.
7) If you do it wrong, you would end up in a world of problems. In that case, it would be better to go with GraphQL.
8) It requires discipline on all sides.
9) Challenging to keep consistency and any governance
1) Easy to start with and produce & consume
2) Lots of hand-holding
3) Contract-driven by nature
4) Easy to keep consistent and to govern
5) Built-in introspection
6) It is closer to SOAP (a protocol) that is good for enterprises
8) One API for all, including specific client needs
9) No reference documentation required
1) It neglects the problems of the distributed system.
2) Query optimization
3) Bikeshedding (content negotiation, network errors, caching, etc.)
4) JSON representation only
5) Server and clients coupled at the client programming time, application state is not driven by the server
6) Too few vendors in the ecosystem and the major one is pretending it owns the show
7) Throws away everything HTTP was figuring out for the last 17 years
REST vs GraphQL use case: When Should you use Rest or GraphQL
On the other hand, GraphQL shows the best performance when the number of queries needs to be reduced to the absolute minimum. With its single query addressing multiple resources, GraphQL can be a good match to this challenge. Considering the fact that in GraphQL data is defined on the client side, and it can be a good solution for cases when there is no dependency between client application and server.
To sum up, we can say that there is no universal solution in the choice of protocols when it comes to create API architecture. Each application is unique and your decision should be based on what is best for your project. Additionally, you can combine API protocols to achieve the most optimal results.