If you are using REST, I have something to tell you. Its time to stop using it. Creating REST APIs which return JSON or XML has many cons. There is a much better way to do it now. GraphQL is a revolutionary alternative to the classic REST API. I have been using GraphQL for some time and have been enjoying it. Today, I will show you the Pros and Cons of both using a REST API or a GraphQL API so you can decide which one to use in your next project.
What is a REST API?
To compare a REST API to a GraphQL one, we first need to know exactly what a REST API is. REST is short for Representational State Transfer. REST is a very popular tool that you can use to provide services to your client. REST sets up an endpoint (e.g. localhost:4000) and provides some services on this endpoint (GET, POST, etc). The client makes a request to this endpoint and receives/changes the data it calls for.
What is GraphQL?
GraphQL was developed by Facebook in 2012. Since then, it has been steadily gaining popularity. GraphQL is a query language for your API. With this method, the client has more ability to narrow down the request for specific data. For example, in my REST API on localhost:4000, I give back a JSON object with an array of my favourite books. Each book has a title, an author, the cost, and the genre. The client just wants the title and author of my favourite book but by using a REST API, I get the whole JSON object back. With a GraphQL server I can make a query like this at localhost:4000/graphql:
query GetBook {
books(place: 1) {
author
title
}
}
With this method, I get just the author and title of my favourite book. I hope that now you can see the power of using GraphQL.
Pros and Cons of using a REST API:
Pros:
- REST is more popular
- You will see more people using REST than GraphQL
- REST is flexible in most areas
- REST can return many different data formats such as JSON or XML
- REST understands files
Cons:
- REST requires multiple round trips
- If I were to retrieve more than one endpoint, I would be making that many separate requests
- Over fetching
- As I mentioned before, REST returns the whole object and the client doesn't have a lot of flexibility to request for specific data
Pros and Cons of using a GraphQL API:
Pros:
- Fetch data with a single API call
- Since GraphQL only has one endpoint, there is only one roundtrip
- Getting exactly what you ask for
- With GraphQL, you can describe exactly what you ask for
- GraphQL Playground
- If you're using GraphQL, the only endpoint in your API is the GraphQL playground. With this playground, you get autogenerated documentation to tailor to your needs
- Errors notified immediately (safer than a REST API)
- With the GraphQL playground, you get immediate and detailed type errors to alert you with the problem right away
Cons:
- Takes longer to learn than REST
- With GraphQL, you need to learn their Schema Definition Language, the playground, and more
- Over the top for smaller applications
- Since REST is easier to learn and performs well for simple apps, GraphQL would be over the top for your normal to-do list
GraphQL Ecosystem
Now that you know the Pros and Cons of REST and GraphQL, I hope you are starting to realise the power of GraphQL. Of course, GraphQL is not perfect but it is definitely something worth migrating to. If you are considering to move over the GraphQL world, the list below will help you to get started with GraphQL right away.
Javascript/Typescript:
Libaries/Tools:
Tutorials:
Flutter/Dart:
Libaries/Tools:
Tutorials:
Python:
Libaries/Tools:
Tutorials:
Conclusion
I hope you have seen the true power of GraphQL in this article and have considered using it in your next project. If you use GraphQL in any other languages apart from Typescript/Javascript, Dart, and Python, then please share the GraphQL ecosystem in that language by commenting below.
Top comments (14)
Time to stop using REST...
Well, that's some loud words, let's just forget about fancy rules that rest requires and think of it as GET/POST/PUT/DELETE requests for simplicity.
You can send these requests from anywhere (web app, server, mobile application, cli) without any special tools (graphql clients). Sure you can send the graphql request without a client also but it will create a real mess in your code, so in 99% you are stuck with graphql client which in case of web applications brings some weight to the bundle.
In terms of server setup – graphql is pretty demanding – you need to setup at least some boilerplate, create schema and manage resolvers. This does not worth your time if you build a small application and need just several simple crud endpoints.
Also do not forget that you need to be careful with how your graphql data is resolved with recursive elements, e.g.
{ author { comments { author { comments { ... } } } } }.Exactly. And I'm really really worried about exposing data structures, and in the case you allow writing back to database: authorization and authentication. It looks like there are solutions out there but none seem ideal at the moment. The overhead of graphql server should not be overlooked as well. It's one more piece of the puzzle you have to handle.
No matter REST, JSON-RPC, or GraphQL, if the data structure (schema) is changed, everything is screwed.
However, with GraphQL you can usually get a type error when you send the query, instead of wondering why the code is accessing a field on
undefined.I would also include to graphql cons:
I'd also add that OpenAPI supports type checking for REST. There are several code generators just like Graphql for multiple languages.
There's another simple alternative to REST. Just implement an API that uses an HTTP POST to send up a JSON request and get back a JSON response, and then design it like a normal RPC API where it's not technically REST because you invent and use VERBS like the whole world used to do before Roy Fielding brainwashed everyone. :)
I already had 20 years of coding experience before Fielding invented REST so he didn't really affect my way of thinking. I always thought the HTTP verbs have absolutely no place in an API, no matter how clever people get at cramming square pegs thru round holes, which is what REST is all about,
In REST everything looks like a noun, because nouns are your only tool, just like if your only tool is a hammer everything starts to look like a nail.
If you are responsible for both backend and frontend, GraphQL just causes unnecessary overhead unfortunately.
With HTTP2, and soon HTTP3, multiple requests are often considered faster than a single request fetching everything.
And if you'd really wanted to, you could create non-cruddy rest endpoints that fetch a mixed bag of data for your tailored needs (that is, you own the backend).
We are currently using json:api which sits on top of the good old REST which gets us most of the described features here like "sparse fieldset" and "includes" and we are very happy with that so far. But there's also a lot of boilerplate on the server side for that.
As many mentioned it's quite wrong assumption. REST has probably been adopted as it fits way better in those use cases than any other model in many client-server communication. Just because Facebook required more and then people found it easier in their use cases doesn't make GraphQL better just different. POST-ing constantly and mutating can be an extreme waste of network traffic and processing power if most clients require quite the same data (extra one-two fields are really not important) which has been frequent in my case - example REST would have no data just GET and all clients use most of the stuff from the DTO. If you build internally stuff and have no intention of exposing API-s how much chance you have of having different requirements per resource? Usually smartphone apps and web use either same data or different resources which is, well resource, so different endpoint. And talking about different architecture using gRPC - we had SOAP didn't go well. Try to pick the right tool for the job and other tools won't look so bad.
Another CON of GraphQL is the inability for optimization beyond DataLoader. As each generation knows only about itself and a limited amount about dependents, the system as a whole cannot use multigenerational joins or optimizations
Public API's do well with GraphQL as the hosts don't know exactly what the callers want from the API. Internal API's are less clear-cut. Often, the caller developer and the host developer are teammates, and the efficiency of a focused REST (or gRPC) call is better
flexibility ∝ efficiency⁻¹
GraphQL Playground is missing a major feature: fill in all the fields of a type.
Altair GraphQL Client has this feature.
altair.sirmuel.design/
I'll check out Altair GraphQL Client. Thanks for the tip!
This is when the server side maintains each version indefinitely. I'm developing the server and I don't want to do that.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.