index.md 10KB
title: REST vs. GraphQL: A Critical Review
url: https://blog.goodapi.co/rest-vs-graphql-a-critical-review-5f77392658e7
hash_url: 1e25f8b077
Are you building an API?
Here is the idea: If you have never heard about the REST architectural style constraints and their implication on the properties of the resulting distributed system and you do not want to (or can’t) educate yourself, use GraphQL.
By going with GraphQL, you will generally end up with a much better API than if you would attempt to build a REST API without understanding its concepts. After all, the lack of REST (and HTTP) knowledge resulted in the boom of “so-called-REST” APIs. And I am sure you know the problems with these APIs first hand. These problems are part of the reason for GraphQL existence.
And it makes complete sense! When time is the essence, when your API is a disposable service, when only one client that you control consumes your API, when you can’t afford to study REST or to learn HTTP in-depth or when you can’t hire someone with the expertise to help you, GraphQL might be the better way to go.
Far too many times, I’d rather see a GraphQL APIs than meet a so-called-REST API that doesn’t even understand the HTTP protocol. I am weary 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 a safe, idempotent and cacheable operation.
I understand there are people who do not have the 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 (and not only them!).
Knowledge is the Key
If you have the luxury being able to study the architectural styles or hire someone to train you, the chances are you are an architect. And as architect your role is to understand the benefits and trade-offs of different architectural styles and the implications of applying the styles constraints on the product you are building.
Of course, different products need different API architectural styles to reach the desired properties and business objectives. And as always, there is no silver bullet. As an architect, it is your duty to have multiple styles under your belt and to know which one to use and when.
REST APIs
True REST APIs are incredibly hard to pull off. They are so rare that outside of my (Good API) clients I could count them on two hands. Besides, it takes educated clients to consume the API correctly.
The reward for the martyrdom and discipline is a system that scales, performs and its components can evolve independently. But, in our fast-paced world, where many apps last only months and where we optimize for now, not later, these seem not to be the properties worth pursuing.
Beware! If you have decided to go with the microservices architecture, REST is probably the best style to enable for independent evolution of services and context separation. It almost feels like REST and microservices architecture were meant for each other.
It took me years to fully comprehend the REST, the mechanics and benefits of the server-driven application state interaction, affordance-centric design and the reality of frameworks and implementations. Depending on where you are in your API journey making a quick judgment on what you think REST is, might lead to the world of problems known as so-called-REST API.
so-called-REST APIs
There are many variants of so-called-REST APIs, that is, APIs that do not follow all the required REST constraints but still dare to label themselves as REST APIs.
The best you can hope for in this category is an API that honors the HTTP protocol and follows its semantics. I call these APIs “HTTP APIs.”
A good HTTP API gives you all the benefits of the existing internet infrastructure but it still tightly couples clients with servers making an independent evolution a chore. Furthermore, it still requires a significant amount of understanding to the protocol on both producer and consumer parts.
If your HTTP knowledge isn’t the strongest and you can’t fix it, it might be a better idea to act as there is no network at all and to use GraphQL than to create an immature so-called-REST API.
GraphQL APIs
Choosing GraphQL gives you easy to design and to amazing to consume API. It also rewards you with effortless consistency between the APIs. By its nature, GraphQL is contract-driven and comes introspection, which is something REST lacks out-of-the-box.
The cost you pay is that your clients have to read the docs (GraphQL schema) at the development time and hardcode the affordances (queries and mutations). This hardcoding of the development-time knowledge leads to clients tightly coupled to the server, but the same also applies to so-called-REST APIs.
Using GraphQL also leaves you vulnerable to what HTTP protocol and the whole internet infrastructure already solved: Scaling, performance, network communication mechanics, and concepts like content, language negotiation, and many others. Some of these can be “added” to a GraphQL API but are not included in-the-box. Adding the functionality that otherwise comes with HTTP leads to bike-shedding. And unfortunately, these home-made-solutions destroys the genius of consistency between GraphQL APIs.
API Design and Over-fetching
There are many misconceptions and false statements about both GraphQL and REST. The one I want to address is about the over-fetching.
Often, we see the claim that GraphQL has the benefit over REST that its clients are not over-fetching data from the server by being able to specify only the attributes they want to receive.
This statement holds true only thanks to poorly designed so-called-REST APIs. Typical examples are naive conversions of SOAP APIs into REST. Other good examples are colossal responses justified by the chattiness of the HTTP1.1 protocol. Either way, the rule of thumb is that if you see an API request or response body with more than a dozen of attributes, somebody didn’t do the API design job properly.
If you really understand your API clients use-cases (and if you use HTTP2), you can design REST API in a such a way that there will be little to no over-fetching and zero impact on the performance.
Besides, how is fetching few more fields with the out-of-the-box caching less performant than fetching only the fields you want but all the way from the origin every single time?
None Shall Escape the API Design
There’s one other aspect of understanding how users interact with your API: The API Design.
In REST you have to go through the exercise of understanding the users’ needs before the API implementation. With GraphQL you can defer the moment of understanding how users consume your API until you start profiling the queries, evaluating their complexity and identifying the slow queries.
In either case, at some point, you will have to understand the user needs and design your API and its implementation accordingly. It would be foolish to think you can create a well-performant API for every use case. You have to make design choices. There is no escaping to this.
Conclusion: Yes Man
Whether you say yes to REST, so-called-REST, or GraphQL, it is essential that you understand the consequences of the noes you tell to the other styles. What aspect are you buying when you say yes to a particular style? What other properties are you loosing when you say no to others?
Chances are you are not a technological company, and you are a product (or service) company. Take a look at the product or service you want to build, what are the business objectives? Understand your choices. Understand your decisions’ impact. And don’t judge by decisions of others; you are unique.