Stop 09 · API DesignTopics · 8/12

gRPC Basics

In short

When your own services call each other thousands of times a second, JSON over REST starts to feel heavy. gRPC sends small binary messages over HTTP/2, with a strict contract both sides share.

A high-performance RPC framework using Protocol Buffers for efficient binary serialization — common for internal service-to-service communication where speed matters more than human-readability.

The blob character pops a capsule into a shiny pneumatic tube.

Think of it like this

The bank's pneumatic tube

Some old banks had tubes linking the counter to the back office. You put a slip in a capsule, it whooshes over, and the reply comes back the same way. The capsule only fits the standard slip. gRPC is that tube: fast, fixed-format messages between known offices.

Watch it happen

Order service charges a payment

Order svc

Payment svc

load payment.proto

1/5Both services share payment.proto, which defines the Charge method and its message types.

The big ideas

What you need to know

The .proto file is the contract

You define services and messages in a .proto file. Tools generate client and server code from it.

Binary over HTTP/2

Protocol Buffers are compact binary, and HTTP/2 carries many calls at once over one connection.

Four call styles

Unary (one request, one reply), server streaming, client streaming and two-way streaming.

Best inside your system

Great between microservices. Browsers can't call plain gRPC, so public APIs usually stay REST or use gRPC-Web.

See it in code

Walk through the code

protobuf

1syntax = "proto3";2package payments;3 4service Payments {5  rpc Charge (ChargeRequest) returns (ChargeReply);6}7 8message ChargeRequest {9  string order_id = 1;10  int64 amount_paise = 2;11}12 13message ChargeReply {14  bool ok = 1;15  string txn_id = 2;16}

1/3A service with one unary method: send a ChargeRequest, get a ChargeReply back.

Load this with @grpc/proto-loader in Node, or run protoc, to get client and server code. Amounts in paise avoid floating-point money bugs.

Save yourself the pain

Common mistakes

Oops

Renumbering or reusing field numbers when editing a message.

Do this instead

Old clients decode by number. Add new fields with new numbers and mark removed ones as reserved.

Oops

Picking gRPC for a public API that browsers call directly.

Do this instead

Browsers can't speak plain gRPC. Use REST or GraphQL at the edge and gRPC between internal services.

Your mission

Make two Node services talk

~40 min

Quick check

Why does gRPC care so much about field numbers like order_id = 1?

Go deeper

1Read a Protocol Buffers (`.proto`) file and identify the defined service and messages.
2Compare gRPC's binary format to JSON's readability and size trade-offs.
3Understand gRPC is typically used between backend services, not directly from browsers.