How to choose HTTP or gRPC for your next API
I recently hosted a Postman livestream, “How We Built it: gRPC Support,” with a few members of the Postman engineering team. During the chat, a lot of great questions were raised about efficiency, how gRPC differs from HTTP-based APIs (like REST and GraphQL), how those are designed and built within Postman, how to do testing, and more. This sparked my interest in doing a deeper technical comparison between the two API types, and why you might choose one over the other.
Related: gRPC vs. REST
HTTP-based API development
Related: What is HTTP?
Most modern REST APIs follow request-response models of communicating between client and server, and build on HTTP version 1.1. This protocol has been around a long time, and is very well supported in software development kits (SDKs), including browser support. The implication of HTTP 1.1, however, is that the protocol relies on a single transactional nature of the communication.
Using an analogy of wanting to ask a friend several questions over the telephone, HTTP 1.1 means we call our friend, ask a question, get an answer, and end the call. We call them again, ask the next question, and end the call again, and so on until we have all of the information we wanted.
REST APIs are widely used, and because their principles are taught to developers, they are well understood within the industry. REST’s alignment with HTTP and its protocol methods make understanding the desired action more clear to developers. These are easier to adopt by other developers because they have a more “shallow” learning curve, typically using JSON data formats for transferring data. JSON has become a highly desired format. Many programming languages serialize and deserialize JSON relatively quickly, again leading to faster implementations. Other formats like XML, BSON, or custom data formats can be used as well, which have their own benefits and drawbacks.
REST APIs offer a flexibility that helps for customization of a company’s API. However, the drawback is that the principles and standards of REST design are loosely followed. The result of this customization is a lack of tools to easily produce documentation or code samples. Postman is a great benefit here, and the OpenAPI Specification can assist as well, to generate documentation and code samples simply by defining the API structure, endpoints, and results. Developers wanting to use the HTTP API must have knowledge of which endpoints are available and how to use them properly.
REST APIs can result in large data payload responses, especially when resources are complex in nature, where developers worry about sending too little data. This over-fetching/under-fetching style of API design sparked a lot of interest in GraphQL, where developers could specify exactly which resources and attributes they wanted in a response. REST may also not be an ideal solution for low-power clients and mobile devices where bandwidth limitations such as data limits make it a less-ideal solution.
GraphQL APIs, which are also generally based on HTTP 1.1 and predominantly use the POST method, remove many of the over-fetching/under-fetching problems inherent in REST APIs of sending “too much” data (that the client discards) or “too little” data (which causes the client to make more calls). GraphQL’s solution was to allow the client to make a request, by name, and inform the server which fields of data it would like to receive in the response. The primary drawback here is that developers need to know the structure of the database to know what is possible to retrieve, and the interaction is still primarily done in text-only formats such as JSON.
gRPC-based API development
Google developed and then released gRPC in 2016 to achieve higher performance communication between microservices. It is an evolved design of RPC, which was created in the 1970s. Designed with HTTP 2.0, it commonly uses Protocol buffers (Protobufs) for a strictly-binary communication format between the client and server.
The primary concepts of building an RPC API are very similar to building a RESTl API. Developers define the rules of the interaction between client and server, like the methods to call. Clients submit the call using arguments to invoke the methods, but unlike REST APIs, which use the HTTP methods like GET and POST to define the desired action, RPC APIs define that method in the URL itself, and the query parameters define the instruction to take.
gRPC implements four kinds of service methods for transfer of data, which allow for flexibility in their overall use:
- Unary: the client makes a single request, and the server sends a single response, similar to REST over HTTP 1.1.
- Client-streaming: the client can send multiple requests to the server, the last of which is an indication that the streamed data is finished, and the server sends back a single response.
- Server-streaming: the client sends an initial request alerting the server that it is ready to receive a stream of data, and the server responds with many responses, the last of which indicates that the stream is complete.
- Bidirectional streaming: after an initial Unary connection between the client and server, both the client and server can send streams of information.
Protocol Buffers allow for a type-safe interface, and are considered to be a “lightweight” communication format. This format is highly compressed and allows for immediate conversion into data structures supported by the client and server’s independent programming languages. (Granted, JSON and text-only formats can also be compressed with many client and server systems supporting compression algorithms like gzip before transport.)
The primary benefit of HTTP 2.0 and the use of Protocol Buffers is speed. Software architect Ruwan Fernando determined that gRPC APIs are generally seven to ten times more performant than REST APIs. It’s important to emphasize that the speed increase is not due solely to gRPC but the underlying network layer and data transfer. Using our earlier telephone analogy to ask a friend some questions, HTTP 2.0 would allow us to call our friend one time, give our list of questions, get our list of answers, and then terminate the call, resulting in less overall traffic to reestablish the connection between each question.
gRPC allows a client to execute a “remote” (server-based) instruction as though it were part of the local system. Because there is less serialization/deserialization required between systems, gRPC is beneficial to low-power clients such as mobile devices and IoT devices.
Another benefit of gRPC is its “discoverability.” As an optional extension, gRPC servers can broadcast a list of requests to clients who request it. This “server reflection” is of tremendous value when working with gRPC APIs. While not a complete replacement for documentation, it does allow easier adoption of an API when developers can get a list of supported instructions. Also, code generation is a feature built into gRPC thanks to its “protoc” compiler.
The main downside for gRPC is adoption, and that adoption is due to the complexity of designing and building a gRPC API. gRPC is generally more difficult to set up and debug since Protocol Buffer messages are binary in nature and not easily human-readable. While RESTful libraries and communication types like JSON are natively supported in browsers, gRPC requires third-party libraries such as gRPC-web, as well as a proxy layer, to perform conversions between HTTP 1.1 and HTTP 2.0.
Third-party tooling and library support is still relatively new for supporting gRPC, and this can lead teams to make more internally-facing gRPC-based APIs than customer-facing external APIs. As a result, Postman’s Public API Network shows only a few gRPC APIs, such as Wechaty and NOVA Security. You can see some examples in a workspace that our DevRel team has put together.
Related: What is gRPC?
Side-by-side comparison of HTTP and gRPC for producing APIs
As an API producer, you have a lot of choices. Postman’s API-first REST APIs are well known for connecting applications and microservices on the internet. REST follows HTTP standards and offers universal support, and is an easier development decision for many teams. While its data transfer is generally larger and its reliance on HTTP 1.1 generates more data transfer to establish connections between requests, its data transfer is easily viewable and readable by developers for software development and debugging purposes.
gRPC’s architectural style is an excellent choice for working across multi-language applications and microservices. Its ability to stream content bidirectionally makes it an efficient choice for systems that require heavier communication loads than single request/response cycles. Its binary data format is far more efficient than RESTful text transfers, and the use of HTTP 2.0 decreases its need to reestablish connections to servers.
Check out the examples in our Public gRPC APIs workspace, and search the Postman Public API Network for others—we’ll be sure to highlight more and more of them in the future! We welcome your feedback and contribution as well, so if you find a great public-facing gRPC API, please make a pull request to our workspace.
Technical review by Joyce Lin.
Excellent article! What ports gRPC use that a sysadmin need to know for firewall rules?
Very useful. thanks for these informations.
multiplexing is a huge advantage for gRPC
Fabulous article. Many of our users struggle to understand why we recommend using gRPC but this article presents the benefits, and the considerations, very clearly.