esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

gRPC: Fast, Typed Calls Between Internal Services

gRPC lets one service call a function on another over the network, using small binary messages sent over HTTP/2. Learn how it works and when it fits.

In short

gRPC lets one service call a function on another over the network, using small binary messages sent over HTTP/2.

10 min readFree

What You Will Learn

Services in a large app often need to ask each other for help. A checkout service might ask a pricing service for a price. gRPC is a tool built for these requests between services. It is a project of the Cloud Native Computing Foundation. In this lesson you will learn how gRPC is built, the four shapes a call can take, a worked ride-hailing example, and the trade-offs compared with REST. By the end, you should be able to say when gRPC is a good choice and when it is not.

Key words

Remote procedure call (RPC)
A way for code on one machine to run a function on another machine and get the answer back.
gRPC
An open source framework for remote calls. It uses Protocol Buffers for messages and HTTP/2 for transport.
Protocol Buffers
A format for describing data and turning it into compact binary bytes. People often call it protobuf.
.proto file
A plain text file where you write down the services, methods and messages for a gRPC API.
Service
A named group of methods that a server offers, like a menu of functions.
Stub
Generated client code that makes a remote call look like a normal function call in your language.
HTTP/2
A newer version of the web's transfer protocol. It can carry many requests at once over one connection.
Stream
A series of messages sent one after another during a single call.
Binary
Data stored as bytes that machines read. It is not readable text.
Deadline
The longest time a client is willing to wait for a call to finish.
REST
A common style for web APIs that uses HTTP and usually sends data as JSON text.
JSON
A text format for data, such as a line like name colon Ann inside curly brackets.
gRPC-Web
A version of gRPC that browser code can use, but it needs a proxy server to translate calls.

How Does GRPC Work?

gRPC starts with a contract. You write the contract once, in a.proto file, and both sides of a call read it. The file lists the services, the methods each service offers, and the messages that go in and out. A compiler tool called protoc then creates code in the language you pick. A server written in one language can talk to clients written in others, because each side gets code that matches the same file. On the server, you write the method logic. On the client, you call the generated stub as if the method were local. gRPC handles the network work in between: it decodes incoming requests, runs your method, and encodes the reply.

What Is the Contract File?

The.proto file is the single source of truth. Protocol Buffers gives you the message layout, and gRPC uses the same file to describe the service. Because both sides build their code from one file, a change that breaks the agreement is easier to spot while building, not after a failed call in production.

Why Use Small Binary Messages Over HTTP/2?

Protocol Buffers turns each message into compact binary bytes. Each field gets a number in the.proto file, and that number, not the field name, appears in the bytes. Field numbers from 1 to 15 take only one byte of overhead, so the most common fields should use those numbers. The bytes then travel over HTTP/2. That means less waiting for new connections, which is one reason gRPC suits busy internal traffic.

The small sample below builds the same small message two ways: as JSON text and as a hand-made binary layout. It only shows the idea. Real code should use the protobuf library and not build bytes by hand.

Python
import json

msg = {"id": 150, "active": True}
as_json = json.dumps(msg, separators=(",", ":")).encode("utf-8")
as_binary = bytes([0x08, 0x96, 0x01, 0x10, 0x01])

print("JSON bytes:", len(as_json))
print("Binary bytes:", len(as_binary))
print(as_binary.hex(" "))

Output

JSON bytes: 24
Binary bytes: 5
08 96 01 10 01

The JSON text takes 24 bytes. The binary layout takes 5. The gap grows with bigger messages, but the exact savings depend on your data. Binary bytes are great for machines and hard for people to read.

Quick check

A teammate opens a gRPC request in a plain text editor and sees unreadable symbols. What is the best explanation?

What Are the Four Call Types?

A gRPC method can take one of four shapes. The shape depends on whether the client, the server, or both send a stream of messages during one call.

  • Unary

    One request goes in and one response comes back. This is the closest match to a normal function call. It fits lookups, price quotes and simple commands.

  • Server streaming

    The client sends one request, and the server sends back a series of messages. It fits live feeds, such as status updates that only flow from the server to the client.

  • Client streaming

    The client sends a series of messages, and the server replies once at the end. It fits uploads, or many small readings that need one summary at the end.

  • Bidirectional streaming

    Both sides send streams during the same call. Each side reads and writes on its own, so neither has to wait for the other to finish. It fits chat or two-way live sessions.

How Do You Pick a Call Type?

Ask two questions. Does the client need to send many messages during one call? Does the server need to send many messages back? If the answer to both is no, a unary call is the simplest choice. Use a streaming shape only when a stream is the natural fit. Streams keep a call open for longer, so they need more care with timeouts and errors.

Tip

Every call can carry a deadline, which is the longest time the client will wait. Set one on every call so a slow service cannot hold the caller forever.

Quick check

A chat feature lets two users' apps send messages to a server and receive new messages from it at any time during one long session. Which call type fits best?

Worked Example: Ride Tracking and Pricing

This example is a teaching design inspired by a ride-hailing app such as Uber. It shows how gRPC could be used. It does not describe how Uber builds its own systems. The app has three parts: a driver's phone, a tracking service that stores where the driver is, and a pricing service that quotes fares. Dispatch, which assigns drivers, asks pricing for fares. The steps below follow one trip.

  1. 1

    Write the contract

    Put the tracking and pricing services in shared .proto files. Every team that builds a client or server reads the same files, so the names and fields match.

  2. 2

    Generate the code

    Run protoc with the gRPC plugin for each language your teams use. Each team gets client stubs and server code that match the contract.

  3. 3

    Stream the location

    While a trip is open, the driver's phone starts one client-streaming call to the tracking service. It sends a location update again and again over that single call. The driver does not wait for a reply after each update.

  4. 4

    Confirm once

    When the trip ends, the phone closes its stream. The tracking service sends one summary reply, such as how many updates it received.

  5. 5

    Ask for a fare

    When a rider asks for a ride, dispatch makes a unary call to pricing. It sends the pickup and drop-off zones and gets one fare back. Dispatch sets a deadline, so a slow pricing reply fails fast instead of blocking the request.

Text
syntax = "proto3";

package rides.v1;

service Tracking {
  rpc StreamLocation (stream LocationUpdate) returns (TrackingSummary);
}

message LocationUpdate {
  string driver_id = 1;
  double latitude = 2;
  double longitude = 3;
}

message TrackingSummary {
  int32 updates_received = 1;
}

service Pricing {
  rpc GetFare (FareRequest) returns (FareReply);
}

message FareRequest {
  string pickup_zone = 1;
  string dropoff_zone = 2;
}

message FareReply {
  int64 price_cents = 1;
}

The file above holds both services. The tracking call uses the stream keyword before its request type, which makes it a client-streaming method. The pricing call has no stream keyword, so it is unary. The driver's updates are a long, one-sided flow, so client streaming fits. A fare is one question with one answer, so unary fits. Both calls use the same contract, so the dispatch team and the pricing team cannot drift apart without noticing.

Trade-offs Compared With REST

gRPC is not the best choice in every case. REST, the common style of web APIs, is simpler to view, call and cache. The points below compare the two.

  • Speed

    Binary messages over HTTP/2 usually mean smaller messages and less overhead. That often helps services that make many small calls, but results vary by workload, so measure your own calls.

  • Strict contracts

    The .proto file is checked when code is built. A mismatch between two services can show up at build time instead of as a surprise at runtime.

  • Streaming

    All four call shapes are built in. REST needs workarounds for long-lived two-way flows.

  • Debugging

    Messages are binary, so you cannot read them with a browser or a simple curl command, which is a text tool for sending web requests.

  • Browser reach

    Browsers do not call gRPC directly in the usual way. Teams need gRPC-Web and a proxy, which adds moving parts.

  • Caching

    REST fits well with HTTP caches and CDNs, which are networks of servers that store copies of files close to users. gRPC does not use those HTTP conventions, so it gets little help from them.

Tip

Do not switch a system to gRPC just because it is newer. First check whether the slow part is the protocol at all. Slow database queries and loops that make needless calls are common causes that gRPC will not fix.

Outside the browser, the trade-off is clearer. gRPC works best for calls between services that one team controls. REST is often a better fit for outside developers, because almost every language and tool already speaks it.

Browser Support

A team that wants a browser to call a gRPC service uses gRPC-Web. This setup works, but it is one more piece to run and debug. For a public website that browsers call directly, plain REST is usually simpler.

Where gRPC Fits Best

Many teams use both styles. REST, or sometimes GraphQL, which is a query style where the caller asks for exactly the fields it needs, sits at the edge where outside clients connect. gRPC runs between the internal services behind that edge. An API gateway, which is a server that receives outside requests and passes them inward, often marks the boundary. Each side then uses the style that suits its callers.

Tip

Move internal services first. Change a public API to gRPC only if outside users ask for it and you have a plan to help them switch.

Quick check

Your team runs 30 internal services. They call each other thousands of times per second using JSON over REST, and the calls are slow. The public website's API is called directly by browsers. What is the best plan?

Sources

How is this lesson?

Last updated on 17 November 2026

Learn with me

Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.