Breaking down REST, GraphQL, RPC
A while back we had a Twitter Space where we talked to some industry experts about APIs and what the differences are between various technologies you can make APIs with.
I’ll try to make some conclusions based on the 2-hour talk, however, be sure to follow Phil and Jens and Vedran to learn more.
Phil Sturgeon, Author at APIs You Won’t Hate (an old book that turned into a community blog and popular slack), API/architecture consultant who helped build most of the OpenAPI tools you know and love. Using his APIs to power his reforestation charity that’s planting trees all over the U.K.
Jens Neuse, CEO and co-funder of Wundergraph. an open-source framework that allows you to quickly build end-to-end typesafe APIs on any backend.
Vedran Cindrić, CEO and co-funder of Treblle. He has been building APIs for the last 10+ years before founding Treblle, an all-in-one API monitoring and observability tool for the entire API lifecycle.
First, let's just write down the definition of an API. So what even is an API?
Technical API definition:
API definition for Muggles:
If you still don’t get it, in short:
whenever you use an application on the web or on the phone to do basically anything (open an article, like something, post, search), in order for the app to show you the thing you want to see it uses waiters (= APIs) to deliver it to you lightning-fast and correct.
That is super oversimplified, continue on reading if you want to find out more.
What Kind of APIs Are There?
The most important “kind” of API that are being used and that is still seeing the most growth are REST-based APIs. The recent state of APIs from 2022 from RapidAPI confirms this.
API usage has seen growth in general and companies have reported 40% increase in usage.
REST 69,3% Webhooks 34,6%Websockets 29,5% AsyncAPI 26,5% Serverless and FaaS 25,4% SOAP 23% GraphQL 18,6% Kafka 12,6% gRPC 8,2%
Types of APIs that are most widespread besides REST are, Webhooks, Websockets, AsyncAPI, Serverless and FaaS, SOAP, GraphQL, Kafka and gRPC.
Every single one of them has seen an increase in being used in production. Even the dreaded SOAP which has been deemed by many as a dinosaur of the past belongs in a museum.
This is probably (in this author’s opinion) due to the fact that many older companies, and especially the slow-to-change public institutions are built and maintained on SOAP (simply because it works, and it's too expensive to change it). So, if you want to connect to their SOAP, you’ll probably have to use SOAP yourself.
Here are the stats on how much all of these have seen an increase in production:
Phil has been trying to standardize on how we talk about all of these kinds of APIs. He says we should be talking about paradigms, specifications and implementations.
“Implementations breakdown into frameworks and platforms.
Paradigms would be REST, RPC, query languages and implementations are things like tRPC, gRPC, and different frameworks that might let you make a RESTful API.
You can have a bunch of different conversation about which paradigms are appropriate in which use cases and obviously which different implementations within these paradigms that will have their own pros and cons.”
How to Know Which One to Use
And we come to the smartest “not-really-an-asnwer” answer: it depends on the use case.
However, Vedran, Phil and Jens managed to talk it out a bit. The first question people should be asking themselves is - do I even need an API? If you only have a simple frontend with little to no need for a backend, then why have an API in the first place?
Jens is one of those result-driven developers. Practicality over using something new and cool (some would say, common sense).
“A lot of new developers like to build with exciting new technology and senior developers are more focused on solving the problem and delivering to their audience. So they’ll use “boring” technology and build “boring” tools, but it will solve a problem. They are not so much concerned about the framework or tools they are using to get there.”
So kids, don’t use a technology just because “everybody” is using it. Focus on problem-solving and figure out what kind of tech will serve you best in the thing you want to build or do.
This, however isn’t just a case with new developers. Phil has seen a lot of companies cross over to the “cool new technology” with no real reason behind it.
“...I’ve seen a huge amount of people wasting a huge amount of time and money, rewriting their APIs for no reason. Just to use the coolest new thing. Eventhough the functionality they needed was completely available to them in paradigm or the implementations they were already using.”
Fundamental Differences between REST, GraphQL an RPC
Keep in mind there are objective pros and cons and subjective pros and cons for using any of them.
“There are different scenarios and use cases that would make one choice objectively more appropriate than the other. But, if nobody has no experience with it, then they are not going to want to use it.” Phil said. He proposed that these are the different approaches in these 3 paradigms.
For RPC, you are literally trying to call a function from a different server. That’s literally what it is. The acronym literally means Remote Procedure Call, you’re literally just calling a function with some arguments.
That is incredibly simple, its on its way to being asynchronous, but its a bit like, you can ask me questions and I will give very short answers.
It's still a request and a response that is very different from a lot of asych API approaches of publisher/subscriber relationships. So it's kind of like “asynch-lite.”
Then there’s GraphQL which is like an RPC that has a standard way of accessing a lot of data. That is incredibly useful when there’s a large number of data and you want to grab a whole bunch of stuff. If RPC is calling a function on a different server than GraphQL is more like an ORM.
REST is a state machine.
State machines come in with a lot of overhead. You simply wouldn’t use a state machine in your little application if you knew that you can get this model from an ORM and do the thing. And then you would use a state machine in a much more larger and complex system. And that complexity is a thing that sometimes you don’t need. Especially if you are the main consumer of that API, why would you be building all this extra information and state controls. Its when you know what those fields do, you can just do the thing.
Diving Deeper into Use Cases
Vedran, a strong voice for REST, proposed a question.
“What I felt always was that if I just want to build a simple API and I pick GraphQL it looks to me I am adding more unnecessary complexity. So in that sense, I always thought, if you have a more simpler, down to earth API or product, it might be more straightforward and simpler to kind of follow a RESTful pattern.”
Jens however thinks that GraphQL can still be used for smaller projects.
“Because if you want to have a GraphQL server, even for a small project, whats the difference between a GraphQL server with one field and one resolver and a REST API with one resource and one controller. Its more or less the same code.”
To know which one to use is a hard question. If we were to simplify we could use one simple to 3 simple questions.
If you can answer those honestly you might come to the same conclusions as Vedran and Jens did.
Jens concluded it with this:
“There’s one very important distinction we have to make between REST and GraphQL.
With REST it always the case that the producer of the API can make intent very clear.
With GraphQL you actually need to understand the API you want to access. So you’ll have to go to GitHub docs and look at the docs. Get exactly the endpoint you want to interact with. And with GraphQL you get 10MB of GraphQL schema and now you have to figure out how to formulate your query.
So, from my point of view GraphQL is a lot easier when you produce the API for yourself, whereas with REST you can make intent to 3rd parties much more clear because you have clear entry points, you have URLs with a specific intent and with GraphQL you have one endpoint and then you have a query and they have 50 different fields and you might be a bit overwhelmed and you don’t exactly know where to start.
All of that is friction, and in this particular use case, REST might be a better choice.”
Vedran also came to a similar conclusion.
“I feel that GraphQL at the same time gives a lot of flexibility, and reduces the amount of work we have to do as backend developers, but also it just moves that complexity, like you said, to somebody who is consuming the API. In this case a fronend developer a mobile developer or somebody else.
And the question that is always in my mind is: does that person know enough and should they know enough about database patterns, design patterns, about what is best for them to do at that moment?”
WRAP UP
So, when we are talking about different kinds of APIs we should probably try to refrain from being subjective with saying one is better than the other one.
Everyone was to eager to think GraphQL is going to be “better REST”, but it turns out it isn’t and REST is here to stay.
What you should use depends on you and your team and who you are building it for and how it is going to be used.
Like always,
Stay hAPI.
