gRPC — An Introduction Guide

  • HTTP/1.1 is textual & Heavy. Microservices exchange information by using huge JSON payload.
  • HTTP is stateless. So additional information is sent via headers which are not compressed.
  • HTTP/1.1 is unary — that is — you send a request and get a response. You can not send another request until you receive the response.
  • HTTP request requires a 3 way message exchange to set up a TCP connection first which is time consuming.


RPC, Remote Procedure Call, is an old mechanism in distributed computing, to execute certain procedure in a remote machine without having to understand the network details. Processes in the same system/different systems which are not sharing the same address space can use RPC for their communication. The call will be made as we would normally invoke a local method call. It follows the client-server model. A client sends a request to the server by invoking a method on the remote server and exchanges messages. RPC provides a well defined interface and type safety.


gRPC is a RPC implementation / framework from Google for inter-microservices communication. Google has been using this for more than 15 years (internal name is Stubby). It is battle tested for more than a decade. Google site shows they have been processing 10 BILLIONS requests / second using gRPC.

gRPC Course:

By the way, I learnt gRPC + Protobuf in a hard way. But you can learn them quickly on Udemy. Yes, I have created a separate step by step course on Protobuf + gRPC along with Spring Boot integration for the next generation Microservice development. Click here for the special link with discount.

gRPC API Types:

REST by default is unary. We send a request and get the response. But gRPC supports streaming requests and responses along with unary APIs.

  • Unary: This is a regular blocking request and response call.
  • Client Streaming: Client keeps on sending a request to the server by using a single TCP connection. The server might accept all the messages and sends a single response back. Use case: File upload functionality
  • Server Streaming: Server sends multiple messages to the client via single TCP connection. Use case: Pagination or Server pushes periodic updates to the client asynchronously.
  • Bi-Directional Streaming: Client and Server can keep on sharing messages via single TCP connection. Use case: Chat application or GPS or Client & server have to work together in an interactive way to complete a task

Service Definition:

Lets assume that we need to a develop a Calculator application which provides the following functionalities.

  • Unary: Finding factorial for the given number
  • Client Streaming: Client sends multiple numbers and the server has to sum them all
  • Server Streaming: Client sends a number to the server for which Server has to find all the factors. For example, If the client sends 6, the server will respond with 2 and 3.
  • Bi-Directional Streaming: Client sends multiple numbers to the server. Server has to check them one by one. If the number is prime, server will pass it back to the client.
syntax = "proto3";

package calculator;

option java_package = "com.vinsguru.calculator";
option java_multiple_files = true;

message Input {
int32 number = 1;

message Output {
int64 result = 1;

service CalculatorService {
// unary
rpc findFactorial(Input) returns (Output) {};
// server stream
rpc getAllFactors(Input) returns (stream Output) {};
// client stream
rpc sumAll(stream Input) returns (Output) {};
// bi-directional stream
rpc findPrime(stream Input) returns (stream Output) {};

gRPC — Project Set up:

  • Create a maven project with following dependencies.
  • The above service definition file is placed in the src/main/proto path
  • Running below command will automatically create all the classes with abstract methods for us to implement the server side functionalities.
mvn clean compile
  • Lets assume that our client implementation is going to be in JavaScript. Protocol Buffers can also generate the client library automatically by using the same service definition in JavaScript to send the requests to the Java back-end server and receive the response.


In this tutorial, we discussed the need for gRPC, API types, project set up etc. Lets further explore how to implement the Microservice/Client-Server application using gRPC and make use of its various RPC types as part of below articles.

  1. gRPC Unary API In Java — Easy Steps
  2. gRPC Server Streaming API In Java
  3. gRPC Client Streaming API In Java
  4. gRPC Bidirectional Streaming API In Java



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Vinoth Selvaraj

Vinoth Selvaraj


Principal Software Engineer — passionate about software architectural design, microservices.