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. 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 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.
When sending a request to a REST API, it is apparent you are using HTTP protocol because your request is sent to a resource URL. A resource URL looks very similar to a URL you type in a web browser to visit a website. When you view a website URL in the browser, you will notice https:// before the website address. This string indicates the protocol used to access the website was Hypertext Transfer Protocol Secure. The web browser acts as a client sending an API request to a server to return a website’s HTML, Javascript, and CSS.
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.
The Payload
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.
Code Generation
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.
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.
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.
Click here to continue reading about the specific considerations for each kind of API.
Top comments (0)