Lesson 14 · Architecture & production

gRPC vs REST

The trade-offs — and the interview question you'll definitely be asked.

Your win: lay out the real differences and pick the right tool for a scenario — the full version of Lesson 1's 10-second rule.

The comparison

	gRPC	REST
Contract	`.proto`, enforced by codegen	OpenAPI (optional, not enforced)
Payload	Protobuf — binary, compact, typed	JSON — text, human-readable
Transport	HTTP/2 (multiplexed)	usually HTTP/1.1
Streaming	native (4 types)	awkward (SSE, websockets)
Browser	needs grpc-web / a gateway	native
Caching	not built-in	HTTP caching works
Debuggability	needs tools (binary)	curl-able by hand

The decision rule gRPC for internal service-to-service: typed contract, small fast binary, HTTP/2 multiplexing, native streaming, low latency. REST for public / browser / third-party APIs: universal, human-readable, browser-native, cache-friendly. Match the choice to who calls it.¹

Our repo does both — deliberately

Every internal call between conversationmgmt, notification, spike, mastermgmt, bob, … is gRPC (Lesson 1). But external clients need REST — so the repo exposes some gRPC methods as REST/JSON through a gateway (Lesson 17), fronted by gandalf. Same .proto, two faces: gRPC for the mesh, REST for the edge.

Anchor spike's SendEmail is internal-only gRPC; its ExternalSendEmail carries an option (google.api.http) annotation so the gateway also serves it at POST /spike/api/v1/proxy/email/send_email (proto/spike/v1/email.proto:144). One proto, both worlds.

Interview nuance Don't say "gRPC is faster, use it everywhere." The honest answer weighs the trade: gRPC's binary contract is a cost at the public edge (no curl, no browser, no HTTP caching), which is exactly why the repo keeps REST there. The senior move is naming when each wins, not declaring a winner.

gRPC — Introduction/FAQ + "gRPC on HTTP/2"

The official framing of what gRPC is good at, and the engineering blog on why HTTP/2 gives it its edge.

→ grpc.io — introduction
→ grpc.io/blog/grpc-on-http2

Check yourself (from memory)

Q1. gRPC's biggest advantage over REST is…

Enforced contract + compact binary over multiplexed HTTP/2, plus native streaming. Those last three are REST's strengths.

Q2. For a public, browser-facing API you'd usually pick…

Browser-native, human-readable, cacheable. gRPC at the edge needs grpc-web or a gateway.

Q3. In our repo, internal service-to-service calls use…

Internal = gRPC; external = REST via the gateway. Both, from one proto.

gRPC vs REST — the one-line decision, and what our repo does.

recall, then click to reveal

Use gRPC for INTERNAL service-to-service: typed contract enforced by codegen, compact binary payloads, HTTP/2 multiplexing, native streaming, low latency. Use REST/JSON for PUBLIC / browser / third-party APIs: universal, human-readable, browser-native, cache-friendly. Our repo does both — internal calls are gRPC; external clients hit REST endpoints that a gRPC-gateway transcodes to gRPC (Lesson 17). Match the choice to the caller.

Want the grpc-web story (running gRPC from a browser) or how GraphQL fits the picture? Ask me.

1. gRPC — Introduction; gRPC on HTTP/2.