gRPC vs REST: a comparison of two ways to build APIs
gRPC and REST are the two approaches most often used to build an API. Find out what each of them is, what traits it has and what it brings to the table.
Today I’d like to examine gRPC and REST more closely – most likely the two approaches used most often to build APIs these days. Both gRPC and REST play a key role in modern API architectures, especially in open-source and microservices-based systems. gRPC in particular enables efficient communication over the HTTP/2.0 protocol and supports many programming languages, which smooths the development of modern applications.
I’ll begin by briefly characterising each tool – what it is and what it has to offer. After that, I’ll compare them across seven categories that I consider the most important for today’s systems.
Here are the categories:
- Underlying Http Protocols
- Supported Data Formats
- Data Size
- Throughput
- Definitions
- Ease of Adoption
- Tooling Support
Why bother?
Mention an API and most people will immediately picture a REST API. Yet REST is only one of many ways to build APIs, and it doesn’t solve every use case. Other approaches exist, RPC (Remote Procedure Call) being just one of them, and gRPC is arguably the most successful framework for doing RPC. That’s what makes the gRPC vs REST question a fair one.
Even though it’s a fairly mature and efficient technology, gRPC is still perceived as new. As a result, it’s less widespread than REST, despite being very convenient in certain use cases. Features such as code generation, which gRPC has built in, often require third-party tools with REST.
My main motivation for this blog post is to make gRPC better known and to highlight the use cases where it really shines.
What is REST?
REST, short for Representational State Transfer, is likely the most widespread way to build an application exposing any kind of API. Its communication relies on HTTP underneath, which lets it take advantage of everything HTTP offers, such as caching.
REST API has been the go-to option for web applications for a long time because:
- It builds on HTTP, the protocol of the web.
- It’s simple and convenient to use, particularly with tools such as browsers and curl.
- It works across a wide range of browsers, devices and languages.
On top of that, since it has been stateless from the very start, REST makes it easy to keep client and server apart. To communicate effectively, the client just needs to know the interface the server exposes and doesn’t depend on the server implementation in any way. Client and server talk in a request and response fashion, where every request is a classic http request.
REST is neither a protocol nor (to some extent) a tool – it’s an architectural approach to building applications. Services built according to REST are known as RESTFul services. Being an architecture, it places a number of constraints on those who use it.
Namely:
- client-server communication
- stateless communication
- caching
- uniform interface
- layered system
- code on demand
REST rests on two key concepts:
- endpoints: a unique URL (Uniform Resource Locator) that represents a given resource. You can think of it as a means of reaching a particular operation or data element over the Internet
- resource: a specific piece of data exposed under a given URL
There is also the so-called Richardson Maturing Model – a model that describes how “professional” a REST API is. Depending on the traits a given API has, it places REST APIs on one of 3 levels (or 4, if level 0 is counted).
One of these traits is that a REST endpoint should use nouns in the URL and the proper HTTP request methods to manage its resources.
Example:
DELETE user/1 instead of GET user/deleteById/1
HTTP methods map to actions as follows:
- GET – fetch a given resource or a collection of resources
- POST – create a new resource
- PUT – upsert an entire resource
- PATCH – partially update a given resource
- DELETE – delete a given resource by id
The maturity model covers far more than this, such as a concept known as HyperMedia. HyperMedia ties together how data is presented and what actions clients are able to perform.
Describing the maturity model in full goes beyond the scope of this blog – you can find more on it here.
Disclaimer: plenty of what this paragraph mentions is more nuanced than presented here. REST is a vast subject that deserves an entire series of articles. Still, everything here is in line with the widely known REST API best practices.
What is gRPC?
It’s another implementation of the fairly old idea of Remote Procedure Call. It was created by people at Google – hence the g in its name. It’s likely the most modern and efficient tool for working with RPCs, and it is also a CNCF incubation project.
gRRC relies on Google’s Protocol Buffers for serialization and on HTTP/2 as the data transport medium, although gRPC can also use JSON as its data layer.
gRPC’s basic building blocks are:
- method: the fundamental building block of gRPC – every method is a remote procedure call that accepts some input and produces output. It carries out a single operation, which is then implemented in whichever programming language you choose. At the moment, gRPC supports 4 kinds of methods: element listy
- Unary – the classic request response model, where the method accepts input and produces output
- Server Streaming – methods take a message as input and return a stream of messages as output. gRPC guarantees that messages stay in order within a single RPC call.
- Client Streaming – the method takes a stream of messages as input, processes them until none remain, and then returns one message as output. As above, gRPC guarantees that messages stay in order within a single RPC call
- Bidirectional Streaming – the method takes a stream as input and returns a stream as output, in effect using two streams, one for reading and one for writing. The two streams work independently, and message order is maintained at the stream level
- service: a group of methods – every method needs a name that is unique within the service. Services also specify aspects such as security, timeouts or retries.
- message: an object representing the input or output of methods.
gRPC API definitions are written as .proto files that include all three basic building blocks listed above. gRPC also ships a protocol buffer compiler that produces client and service code from our .proto files.
The server-side methods can be implemented in any way we like. We just need to respect the API’s input-output contract.
The client side has an object called the client (or stub) – similar to an http client. It is aware of all the server’s methods and simply takes care of invoking remote procedures and returning what they respond with.
gRPC vs REST - comparison
Underlying HTTP Protocol
This first category is probably the most important, since its impact shows up in the others too.
Generally, REST follows the request-response model and relies on HTTP/1.1 for transport. For streaming of any kind or longer-lived connections, we need a different protocol such as WebSocket (you can read more about them here).
We could also write some hacky code to make REST look like streaming. Moreover, since it uses HTTP/1.1, REST needs a separate connection for each request response exchange. This can cause trouble for long-running requests or when network capacity is limited.
Naturally, HTTP/2 can be used to build REST-like APIs as well, but HTTP/2 isn’t supported by every server and library yet, so issues may crop up elsewhere.
gRPC, by contrast, works exclusively over HTTP/2. This makes it possible to send many request-response pairs over a single TCP connection, which can give our application a considerable performance boost. What’s more, by using HTTP/2, gRPC benefits from advanced features such as flow control, which allows data to be transmitted efficiently during bidirectional streaming.
Result: A narrow win for gRPC
Supported Data Formats
In the default scenario, where a REST API runs over HTTP/1.1, many formats can be supported.
As a rule, REST places no restrictions on the format or style of messages. In practice, any format that can be serialized to plain old text will do, so we can pick whatever fits a given scenario best.
JSON is without doubt the most popular format for sending data in REST applications. XML takes second place due to the large number of older/legacy applications.
When REST is used with HTTP/2, however, only binary exchange formats are supported. In that case protobuf or avro are options. This approach naturally has its downsides, which are covered in the following points.
gRPC, for its part, supports just two data exchange formats:
- Protobuf – the default
- JSON – for integrating with an older API.
If you choose to go with JSON, gRPC will use JSON to encode messages and GSON as the message format. Using JSON also involves some extra configuration – here is the gPRC documentation explaining how.
Result: REST wins, since it supports more formats.
Data Size
gRPC uses a binary data exchange format by default, which DRAMATICALLY shrinks the messages sent over the network. According to research, the size in bytes drops by about 40-50% – and in one of my past projects I saw as much as 50-70% less.
The article above offers a fairly thorough size comparison of JSON and Protobuff. Its author also shared a tool that generates JSONs and binary files, so you can repeat his experiments and compare the outcomes.
The objects used in the article are fairly simple. Nonetheless, the general principle holds: the more nested objects and the more complex the JSON structure, the heavier it gets relative to protobuf. A 50% size advantage for protobuf is a sensible baseline.
Using a binary exchange format for REST can shrink or even remove the gap. However, this is neither the most common nor the best-supported way of building RESTful APIs, so you may run into other issues.
Result: gRPC wins in the default case; if both use a binary data format, it’s a draw.
Throughput
Once more, with REST it all comes down to the underlying HTTP protocol and the server.
In the default case of REST over HTTP/1.1, not even the fastest server will outperform gRPC, particularly once you factor in the cost of serializing and deserializing JSON. That said, the gap appears to shrink once we move to HTTP/2.
When it comes to maximum throughput, both rely on HTTP as the transport medium, so both can in principle scale indefinitely. It therefore all hinges on the tools we use and on what exactly our application does, since the design itself imposes no limits.
Result: gRPC in the default case; with binary data and HTTP/2 on both sides, a draw or a narrow win for gRPC.
Definitions
Here I’ll explain how messages and services are defined in each approach.
In most REST applications, we simply declare requests and responses as classes, objects or whatever structure the language in question offers. We then depend on the available libraries to serialize and deserialize JSON/XML/YAML or whichever format we need.
There are also ongoing efforts to build tools that generate code in a chosen programming language from REST API definitions in swagger. They appear to be in an alpha stage, though, so you may still hit bugs and smaller issues that make them hard to use.
For a REST application, binary and non-binary formats differ little, since the principle is roughly the same in both. With a binary format, we just define everything the way that particular format requires.
We also defined our REST service using methods or annotations provided by the underlying library or framework. That tool then takes care of exposing it, along with the rest of the configuration, to the outside world.
With gRPC, protobuf is the default and, in practice, the only way to write definitions. Everything – messages, services and methods – has to be declared in .proto files, so things are quite simple. gRPC defines services and data structures with the Protocol Buffers interface description language (IDL), which allows for efficient, language-neutral serialization and boosts performance in service-to-service communication.
Next, the tool supplied with gRPC generates the code for us, leaving us only to implement our methods. Once that’s done, everything should work as expected.
Protobuf also supports imports, which lets us split our setup over multiple files fairly easily.
Result: There’s no winner in this category, only the description plus my advice: go with whichever approach fits you best.
Ease of Adoption
Here I’ll compare how well each approach is supported by libraries/frameworks in today’s programming languages.
Generally speaking, every programming language (Java, Scala, Python) I’ve encountered in my short software engineering career offers at least 3 major libraries/frameworks for building REST-like applications – and roughly as many libraries for autospring JSON to objects/classes.
What’s more, since REST relies on human readable formats by default, newcomers find it easier to debug and work with. This can also affect the pace at which new features are delivered and make it easier to tackle bugs showing up in your code. REST APIs are frequently built with third-party developers in mind, which ensures long-term stability and backward compatibility.
In short, support for REST-style applications is very good at the very least.
gRPC itself offers a client library for more than 8 popular programming languages. That’s typically sufficient, since these libraries include everything needed to build a gRPC API. I also know of libraries offering higher-level abstractions for Java (through a Spring Boot Starter) and for Scala.
Another point is that REST is now regarded as a global standard and the default starting point for building services, whereas RPC, and gRPC specifically, are still seen as something new even though they’re fairly old by now.
Result: REST, since it’s more widely used and surrounded by far more libraries and frameworks.
Tooling Support
Since libraries, frameworks and overall market share were discussed above, this part focuses on the tooling available for each style – that is, tools for testing, performance/stress testing and documentation,
Automated tests/Tests
To begin with, for REST, tools for writing automated tests are either part of various libraries and frameworks or exist as standalone tools made just for this, such as rest assured.
For gRPC, we can generate a stub and use it in tests. To be even stricter, we can run the generated client as a standalone application and build our tests against the real service on top of it.
When it comes to external tools that support gRPC, I know of:
- The Postman app’s gRPC support
- The JetBrains HTTP client built into their IDEs, which can handle gRPC too with a little configuration
Result one: REST wins, though things appear to be getting better for gPRC.
Performance tests
REST has a clear edge here, as tools such as JMeter or Gatling make stress testing REST APIs fairly simple.
Sadly, gPRC lacks comparable support. I know that the Gatling team has included the gRPC plugin in the current Gatling release, so things appear to be improving.
Until now, though, all we had was a single unofficial plugin and a library named ghz. They’re all fine – the support just isn’t on par with what REST gets.
Result two: REST wins, though things appear to be getting better for gPRC – once again ;)
Documentation
When it comes to API documentation, REST wins yet again, with OpenAPI and swagger widely used across the industry and serving as the de facto standard. Nearly every REST library can expose swagger documentation out of the box or with very little work.
gRPC, unfortunately, has no equivalent.
The question, however, is whether gRPC needs such a tool in the first place. gPRC is by design more descriptive than REST, so extra documentation tools may .
Generally, .proto files describing our API are more declarative and concise than the code that builds a REST API, so perhaps gPRC doesn’t require any further documentation. I’ll let you decide.
Result three: REST wins, but whether gRPC needs documentation remains an open question.
Overall outcome of the gRPC vs REST contest: a clear win for REST.
gRPC vs REST - summary
Here’s how the final score table looks.
The points are split evenly between the two styles: three wins each and one category with no clear winner.
There’s no silver bullet – consider which categories matter most for your application and choose the approach that came out on top in most of them. That’s my advice, anyway.
Personally, I’d give gRPC a go whenever I can, since it served me really well in my most recent project. It may turn out to be a better pick than good old REST.
Thanks for your time.