APIs specify how different software components should interact and communicate programmatically and are the “glue” that allows separate system components to exchange data using an architectural model (such as REST). APIs act as a “liaison” between system components written in different programming languages in microservices architectures. These components require an interface for communication. This interface is the API.
Not only are APIs interfaces for microservices, but they are also independent pieces of functionality with a lifecycle similar to standard software.
There are many types of API architectural styles. This article will discuss the similarities and differences between two popular architectural styles: REST APIs and gRPC APIs. We will explore their strengths, weaknesses, and potential use cases.
What is an API architectural style?
An API architectural style is a model, or set of rules, for building an API. REST and gRPC are API architectures that constrain API design according to distinct architectural principles. For example, REST APIs must follow REST principles such as client-server separation, statelessness, and cachability. gRPC APIs must be general purpose, performant, payload agnostic, and support multiplexed streaming. In summary, RESTful APIs adhere to REST architectural standards and practices, while gRPC APIs adhere to gRPC standards.
Architectural styles define the interaction between clients and API servers. In other words, they determine how clients access and manipulate data the API exposes. An architectural style determines how clients structure requests and what parameters can be sent to affect the server response. They tell the client what response to expect from the API based on a specific input. Finally, they determine the communication mode, communication protocol, payload format, and the entities exposed by the API (data object vs. procedure).
What is a REST API?
REST APIs use HTTP 1.1 protocol for data transmission. A REST API is a web service because it uses HTTP protocol to transmit messages. Web services deal with the interaction between client applications and API servers. Using this protocol, a client sends an HTTP request for data to an API Server, and then the server sends an HTTP response with encoded data back to the client.
The HTTP protocol used by REST APIs allows platforms and systems written in different programming languages to interact with one another. For example, a client application written in Python can interact with an API server written in Java. This interoperability between systems makes web services very popular in modern software development – REST APIs in particular.
REST’s separation of concerns for the client and server makes it attractive for many projects, including mobile and web development terms. In particular, its features work well for cloud applications, cloud computing, and microservices.
Here are the steps for sending a REST API request:
- Decide which resource URL to call
- Calculate the parameter values to use (if any)
- Use a third-party tool to translate the request into the client programming language
What is a gRPC API?
The “RPC” in gRPC stands for the Remote Procedure Call (RPC) model. The “g” in gRPC stands for Google. Hence, gRPC is Google’s implementation of RPC. Google created a variant of gRPC to facilitate fast communication between microservices. The original RPC has been mostly replaced by gRPC.
Clients access and manipulate data exposed by gRPC APIs differently than REST APIs. REST allows clients to access “data objects” using resource URLs. With REST, the data, in the form of a resource, is front and center. How an API processes a request and sends data back is hidden from the client.
gRPC, in comparison, allows clients access to API “procedures” that manipulate data. The procedure is the action taken on the data. The data itself, unlike a REST API resource, is hidden.
Here are the steps to compose a gRPC request:
- Decide which procedure to call
- Calculate the parameter values to use (if any)
- Use a code-generated stub to make the call
In the process above, you’ll notice a procedure is called rather than a resource URL. Unlike REST, a client sending a request to a gRPC API does not need a third-party tool to convert the message. Instead, the client uses a code-generated stub generated by gRPC software.
What is the difference between REST API and gRPC?
The following are some differences between the REST and gRPC architectural styles.
API Exposed Entities
As mentioned before, REST exposes resource URLs and gRPC exposes procedures to clients to access the API. It is easier to send REST API calls since you can type Resource URLs into a browser, use cURL to issue commands to the API, or run a script from the terminal. gRPC, on the other hand, requires clients and servers to use gRPC software to send and receive requests, respectively. In addition, clients and servers must incorporate code generated by gRPC into their build processes.
HTTP 1.1 vs. HTTP 2.0
REST APIs use HTTP 1.1 communication and gRPCs use HTTP 2.0 protocol.
The same process occurs when sending a request to a REST API. The HTTP transport details (the Resource URL) are visible to the client and are used to send the request. REST API designers also have control over the structure of resource URLs. Another benefit of HTTP 1.1 APIs is that clients and servers can use web technologies that are more widely available than those offered to gRPC APIs.
gRPC uses HTTP, but the client and server never see how a gRPC request is mapped to the HTTP protocol. This is because the gRPC model is layered over HTTP. gRPC has already decided how API requests are mapped to HTTP requests and does not expose this information. Clients do not need to worry about how requests are mapped to HTTP. Instead, the client follows the defined message standards for sending a gRPC message and does not send an HTTP request directly. Unlike REST, API designers do not have access to HTTP transport details.
Client-server communication Model
In the case of REST, HTTP 1.1 can only handle unary streaming. This kind of streaming involves a client sending one request at a time and the server sending one response.
In the case of gRPC, HTTP 2.0 allows for the following streaming options:
- Unary – Same as HTTP 1.1.
- Server Streaming – A server can send multiple messages back in response to a single request sent by the client. The last message indicates that the transmission has been completed.
- Client Streaming – One client can send multiple messages to the server at the same time. The server responds with one response.
- Bi-directional streaming – The server can process multiple requests from multiple clients at the same time and send back multiple responses at the same time. In this form of streaming, both the clients and the server send messages simultaneously. The client is in charge of ending the streaming.
REST uses JSON as the primary message format which is human-readable and does not follow a strict structure.
Unlike REST JSON messages, gRPC messages are not human-readable. This is because gRPC serializes message payloads and compresses them. Because gRPC messages are serialized, they can be transmitted faster than JSON.
REST API clients rely on third-party tools to convert the message to the appropriate programming language. When an API server receives a request, it must convert it to the server’s programming language.
In gRPC, clients do not need third-party tools to convert messages. Instead, clients use code-generated stubs generated by gRPC software. On the server side, gRPC has the built-in conversion of messages to the server’s programming language.
REST and gRCP Feature Comparison
Now we will compare the features of REST to gRPC.
|Exposed Entities||Resource URLs – HTTP transport details are exposed to the client and server.||Procedures – HTTP mappings are hidden from the client and server.|
|HTTP Protocol||HTTP 1.1 – Only supports unary streaming.||HTTP 2.0 – Supports bi-directional streaming but is less browser compatible than HTTP 1.0.|
|Browser Support||REST’s use of HTTP 1.0 and JSON message format gives it universal browser support.||gRPC has less browser support because it requires a proxy layer and gRPC-web to convert HTTP 1.1 and HTTP 2.0 back and forth.|
|JSON – a human-readable format that has to be serialized and converted into both the client and server’s programming language. JSON payloads are also larger than gRPC payloads, resulting in slower transmission than gRPC payloads.
JSON is flexible because it does not need to adhere to a strict structure.
REST also supports other message formats like XML, HTML, and YAML.
|Protobuf messaging format – gRPC serializes and compresses payloads using a Protocol Buffer which reduces file size. As a result, they can be transmitted faster than JSON payloads.|
|Code generation||REST does not have built-in code generation. Instead, you must use a third-party service to produce the code for an API request.
On the server side, API requests must be converted to the server’s programming language.
|gRPC has built-in code generation and uses a compiler to convert programming languages.|
Crawling the API
|It is easy for an application to crawl an entire REST API like a web browser crawls a web page because metadata is not required, unlike gRPC.||Each entity (the equivalent of a resource in REST) belongs to a separate API and requires special software and metadata to crawl it.|
|Cachability||While not handled directly by the REST API, clients can effectively cache HTTP responses. Caching is made possible by REST’s separation of endpoints using URLs and its use of HTTP headers to perform CRUD operations.||gRPC API requests are sent using the POST method which is not cachable.|
|Partial update mechanisms||The Open API spec allows for the PATCH method which updates a resource.||gRPC provides no such method.|
|Implementation||Fast implementation is possible due to the wide availability of third-party tools.||Implementing a gRPC API is slower due to the lack of tools available to quickly build services. gRPC is not as popular or as old as REST, so there are fewer tools available.|
When to use REST vs. gRCP?
REST and gRPCs features make them suited for different use cases.
Best for Public Web Services: REST
REST’s features are well-suited to public web service APIs. REST uses the HTTP 1.1 protocol which has universal browser support. gRPC, on the other hand, is less compatible since it uses HTTP 2.0. While gRPC’s payload is smaller, REST’s primary payload format, JSON, is more flexible and friendly to browsers. REST also allows you to use other message formats HTML, plain text, XML, and YAML which adds to its flexibility.
Best for Internal APIs, IoT, and mobile: gRPC
gRPC has features that make it suited for internal APIs, IoT, and mobile development. These applications benefit from gRPC’s bi-directional streaming, small payload sizes, and built-in code generation. gRPC’s small message size makes it more performant and scalable than REST for these applications.
gRPC’s low browser support makes it suited to internal APIs (non-public) and mobile development. Mobile applications usually do not require a browser, and gRPC’s small message size can preserve the processing speed of the mobile device.
IoT APIs need bi-directional streaming because many devices may send messages to an API server concurrently. gRPC can process and respond to multiple requests from multiple clients at the same time. REST, on the other hand, only supports unary communication. IoT APIs also require lightweight messaging because of constrained bandwidth. Finally, it is easier to use gRPC to connect Internet of Things (IoT) devices such as phones to backend APIs.
Best for microservices: The jury is out
REST and gRPC are both used for microservices. While REST is more widely used for microservices, gRPC’s features are particularly suited to this domain.
Microservice architectures can leverage gRPC’s built-in code generation to allow microservices written in different programming languages to communicate. gRPC’s payload size and bi-directional streaming also allow faster and more efficient communication between microservices.
Read more: How to Write API Documentation
How to document REST and gRPC APIs
REST and gRPCs require reference documentation that provides a comprehensive manual of API components and processes. In the case of REST, that means descriptions for all resources, endpoints, parameters, etc. Reference documentation is usually generated by a third-party tool that relies on the API conforming to a predefined structure, like OpenAPI. Both APIs also require API conceptual documentation for getting-started guides, use cases, and tutorials. As opposed to reference docs, conceptual documentation is human-written.
Next, we will discuss some specific considerations for each kind of API.
OpenAPI is a RESTful API specification describing APIs that conform to RESTful architecture. A specification provides an interface for letting humans and computers understand an API and how to interact with it. APIs that conform to the OpenAPI specification can leverage the plethora of documentation tools available such as Document360, Swagger, Stoplight, or Readme.io. It is also possible for other kinds of APIs to adopt the Open API spec.
Also, check out our article on SwaggerHub Alternatives
gRPC’s addressable entities, as procedures, are the opposite of Open API’s resources (data objects). And so, gRPC APIs are not the best candidate for applying the Open API standard. The documentation tools available to gRPC are far fewer in number compared to REST APIs.
However, some APIs are implemented in gRPC but use the Open API standard as its specification language. Doing so reverses gRPC’s procedural entities and focuses client interaction on resource data objects.
Instead of accessing procedures, gRPC can expose entities through HTTP URLs like REST APIs. By using OpenAPI, gRPC APIs can take advantage of the same robust tools as REST for documentation.
Retrofitting an existing gRPC API to conform to Open API is unlikely because it is difficult. That is why it is more likely for a new gRPC API to be developed from the ground up with Open API in mind. Some tools allow you to use protocol buffers to create a combination REST/gRPC API that generates an Open API spec. The general process involves annotating gRPC services using OpenAPI options and mapping those services to REST API calls in the server definition. You can then generate and serve swagger documentation from the command line like a REST API.
Also Read: REST vs. SOAP: What is the difference?
REST and gRPC are two API architectural styles that both provide a set of rules for building an API. Choosing which architectural style to use depends on the kind of application you wish to build. REST’s features make it well-suited for public-facing APIs that require browser support, and gRPC’s small payloads and bi-directional streaming work well for mobile development and IoT. Both are viable choices for microservices architectures, but REST remains king in this domain.
Ready to take your API documentation to the next level? Book a demo with Document360 today!Book A Demo