loading...
Cover image for Time to stop using REST...

Time to stop using REST...

hb profile image Henry Boisdequin Updated on ・4 min read

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.

Alt Text
Source

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
  }
}
Enter fullscreen mode Exit fullscreen mode


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.

Discussion

pic
Editor guide
Collapse
rtivital profile image
Vitaly Rtishchev

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 { ... } } } } }.

Collapse
yellow1912 profile image
yellow1912

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.

Collapse
jfbrennan profile image
Jordan Brennan

It is not time to stop using REST, but it is time - it's always time - to use the right tool for the job.

Some requirements are best met with REST, some with GraphQL, some with gRPC, etc. etc. etc.

Having said that, I am jealous! I have only played with GraphQL, never used it in production yet.

Collapse
yoursunny profile image
Junxiao Shi

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.

Collapse
pjotre86 profile image
pjotre86

When you do REST and follow HATEOAS you can change your data structures. But who's got time for that 😬

Collapse
yoursunny profile image
Junxiao Shi

I see, GitHub API has HATEOAS. However, if the client code isn't an AI, it still breaks when the schema changes.

Thread Thread
pjotre86 profile image
pjotre86

Yes, github is not a bad example. If you built your client according to the github API documentation it'll probably never break. Because then you alway specify the version of the resources you're dealing with in the media type header, see docs.github.com/en/free-pro-team@l...
Versioning based on media types prevents stuff to break when an API introduces breaking changes. However, it only works when the client is aware of it and adheres to this flow. Also it gets more complex on the server side, as you have to be able to provide multiple versions of the same resource at the same time. That's what I meant with "who's got time for this"...

Thread Thread
yoursunny profile image
Junxiao Shi

This is when the server side maintains each version indefinitely. I'm developing the server and I don't want to do that.

Thread Thread
pjotre86 profile image
pjotre86

Yes, and that's why you have this problem. I just want to point out that it is possible to introduce breaking changes to a REST API without breaking clients...

Collapse
aghost7 profile image
Jonathan Boudreau

I would also include to graphql cons:

  • Caching is more difficult. Especially for edge.
  • Not as much tooling for implementing microservices. You'll need to roll your own gateway.
  • Monitoring endpoints is going to require a custom solution afaik, since graphql doesn't respect status codes.

I'd also add that OpenAPI supports type checking for REST. There are several code generators just like Graphql for multiple languages.

Collapse
wclayferguson profile image
Clay Ferguson

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.

Collapse
michi profile image
Michael Z

If you are responsible for both backend and frontend, GraphQL just causes unnecessary overhead unfortunately.

Fetch data with a single API call

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).

Collapse
richardhaven profile image
No Clever Code

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⁻¹

Collapse
greenroommate profile image
Haris Secic

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.

Collapse
phyberapex profile image
PhyberApex

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.

Collapse
yoursunny profile image
Junxiao Shi

GraphQL Playground is missing a major feature: fill in all the fields of a type.
Altair GraphQL Client has this feature.
altair.sirmuel.design/

Collapse
hb profile image
Henry Boisdequin Author

I'll check out Altair GraphQL Client. Thanks for the tip!

Collapse
perpetualwar profile image
Info Comment marked as low quality/non-constructive by the community. View code of conduct
Srđan Međo

Another click bait title with silly premise. Since when this became norm on dev?