API Patterns and Practices: gRPC
Designing gRPC APIs well, with runnable examples in Quarkus and Python against one Protobuf contract.
What this site is
A chapter-based, hands-on path to designing gRPC APIs well, built around a
single Protocol Buffers contract — linted
and breaking-change-gated by Buf — for a
shipping and cargo domain. gRPC here is the internal, latency-sensitive
routing and tracking service that the sibling
REST
booking service calls. Every hands-on chapter ships the same example in
both Quarkus and Python, generated from that one proto, and
CI asserts each response against it — an OK that carries a
contract-violating message fails the build. You work through the four RPC
types, deadlines and the rich error model, schema evolution, backend
concurrency, streaming and backpressure, performance tuning, security,
observability, the Kubernetes load-balancing problem, gRPC-Web and
transcoding. It assumes you can read Java and Python; it is not a tutorial in
either language. The code tabs are built to admit Go and C++ later. All
container images are UBI-based, and the stack runs on Docker Compose,
minikube, and OpenShift Local.
Prerequisites & the Lab
Get the contract-first (proto + Buf) toolchain running locally: Quarkus, Python, Docker Compose + LGTM, and the shipping/cargo domain.
Why gRPC, and the Decision Lens
Decide whether gRPC fits an interaction and classify any call on five axes.
Protocol Buffers: the Contract Language
Model the shipping domain in protobuf and make it the Buf-enforced single source of truth both stacks generate from.
HTTP/2 & the Four RPC Types
Explain why gRPC is fast and implement and choose among all four RPC shapes.
Reliability: Deadlines, Errors & Interceptors
Make calls fail correctly and bound their own blast radius.
Schema Evolution & the Living Contract
Design and evolve a proto without breaking clients, enforced by CI.
Concurrency & Long-Running Work
Serve I/O-bound RPCs without exhausting threads and model work that outlives one call.
Streaming at Scale & Performance
Run streaming safely under load and tune and benchmark the service.
Security
Encrypt, mutually authenticate, and authorize gRPC calls.
Observability, Mesh & Load Balancing
Trace an RPC across the REST to gRPC seam and run gRPC correctly behind Kubernetes.
Browsers, Transcoding & Cross-Protocol
Expose gRPC to a browser or REST client and choose gRPC vs alternatives, including over HTTP/3.
Testing & Debugging
Prove conformance and debug a gRPC service end to end.
Running It & the Final Project
Run, observe, and defend a complete gRPC system across all three tiers.