gRPC & Protocol Buffers Vocabulary: 30 Terms for API Developers
gRPC service definition, Protocol Buffers, streaming types, interceptors, deadlines, and client generation vocabulary.
If you work with microservices or distributed systems, you have almost certainly heard colleagues mention gRPC in code reviews, architecture meetings, or Slack threads. gRPC is a high-performance remote procedure call framework developed by Google, and it uses Protocol Buffers (often called “protobuf”) as its default serialisation format. Together, they power communication between services at companies ranging from early-stage startups to large engineering organisations. Mastering the vocabulary around gRPC and protobuf will help you participate confidently in technical discussions, write clearer documentation, and understand pull request comments without having to ask for clarification every time.
Core Concepts: Defining Your API
Proto file — a plain-text file with a .proto extension that describes the shape of your data and the operations your service exposes. Everything starts here; the proto file is the single source of truth for your API contract.
“Has the proto file been committed yet? I want to start generating the client stubs.”
“Don’t change the proto file without running it past the backend team first — any breakage will affect three other services.”
Service definition — the block inside a proto file that declares which remote methods a server exposes. It is the gRPC equivalent of an interface or a controller in a REST API.
“The service definition looks clean, but you’re missing a method for bulk updates.”
“We agreed the service definition would live in the shared-protos repo so all teams pull from one place.”
Message — a structured data type defined in a proto file, similar to a class or a struct. Messages describe both request and response payloads.
“Your
CreateOrderRequestmessage is missing thecurrency_codefield — add it before the next release.”
“We reuse the same
UserProfilemessage across four different RPC calls to keep things consistent.”
Field number — a unique integer assigned to each field inside a message. Protocol Buffers use field numbers — not field names — to identify data on the wire, which is why they must never be changed or reused once a schema is in production.
“You can rename the field freely, but never reassign its field number — that will corrupt existing serialised data.”
“We ran out of single-digit field numbers, but that’s fine; just keep them sequential and it won’t affect performance.”
Protoc compiler — the command-line tool (protoc) that reads .proto files and generates language-specific code, such as Go structs, Java classes, or TypeScript interfaces. Plugins extend it to produce additional outputs like gRPC stubs or OpenAPI specs.
“Run protoc after every schema change — the generated files should always be committed alongside the proto file.”
“Our CI pipeline runs protoc automatically so nobody accidentally ships stale generated code.”
RPC Types and Communication Patterns
gRPC supports four distinct communication patterns. Understanding the differences will help you choose the right one during design discussions.
Unary RPC — the simplest pattern: the client sends one request and waits for one response. This behaves much like a traditional HTTP request.
“For the login endpoint, unary RPC is fine — there’s no reason to stream a single token back.”
Server-streaming RPC — the client sends one request and the server responds with a stream of messages. Useful for things like live data feeds or large result sets.
“We switched the search endpoint to server-streaming so results appear incrementally rather than all at once.”
“Server-streaming made the dashboard feel much faster — users see the first rows immediately.”
Client-streaming RPC — the client sends a stream of messages and the server replies with a single response once the stream is complete. Common for file uploads or batch ingestion.
“The telemetry endpoint uses client-streaming — devices push hundreds of readings and get a single acknowledgement back.”
Bidirectional-streaming RPC — both the client and server send independent streams of messages simultaneously. This pattern suits real-time collaboration tools, chat systems, and live game state synchronisation.
“The multiplayer feature needs bidirectional streaming; anything else would introduce too much latency.”
“Bidi streaming is powerful but harder to reason about — make sure you handle half-close correctly.”
Stub — the auto-generated client-side code that lets you call remote methods as if they were local functions. The stub handles serialisation, network transport, and deserialisation transparently.
“Once protoc generates the stub, calling the remote method feels no different from a local function call.”
“The stub for the payments service is in the
/generatedfolder — import it and you’re good to go.”
Channel — a persistent connection between a gRPC client and a server, managing the underlying HTTP/2 connection, load balancing, and reconnection logic.
“Don’t create a new channel per request — instantiate one at startup and reuse it throughout the application lifetime.”
“The channel supports name-based load balancing, so you can point it at a DNS entry and let it distribute traffic.”
Reliability, Observability, and Security
Interceptor — middleware that runs before or after a gRPC call on either the client or server side. Interceptors are the standard place to add cross-cutting concerns such as logging, authentication, metrics collection, and request tracing.
“Add an interceptor for distributed tracing so every call automatically propagates the trace ID.”
“The auth interceptor validates JWTs on every inbound request — you don’t need to check the token manually in each handler.”
Deadline / Timeout — a point in time (deadline) or a duration (timeout) after which a gRPC call is automatically cancelled. Setting deadlines prevents slow upstream services from cascading failures across your entire system.
“Always set a deadline on outbound calls — without one, a hanging dependency will block your goroutine indefinitely.”
“The deadline propagates through the context, so child calls are cancelled automatically when the parent times out.”
Status code — a standardised code that gRPC returns alongside every response, indicating whether the call succeeded or describing the type of failure. Examples include OK, NOT_FOUND, UNAVAILABLE, and DEADLINE_EXCEEDED.
“Return
INVALID_ARGUMENTwhen the client sends bad input — don’t useINTERNALjust because it’s convenient.”
“The retry logic is keyed on
UNAVAILABLEandDEADLINE_EXCEEDEDstatus codes only.”
Metadata — key-value pairs attached to a gRPC call, similar to HTTP headers. Metadata is used to carry authentication tokens, request IDs, locale information, and other contextual data that is not part of the message payload.
“Pass the correlation ID in outgoing metadata so every downstream service logs it for tracing.”
“We attach the user’s locale to the request metadata instead of putting it in every message type.”
Wire format — the binary encoding that Protocol Buffers use to serialise messages before sending them over the network. It is compact and fast, but not human-readable — use protoc --decode or a tool like grpcurl when you need to inspect traffic during debugging.
“The wire format is significantly smaller than JSON, which matters when you’re sending millions of messages per second.”
“If you need to inspect the wire format in staging, use grpcurl — it decodes protobuf payloads into readable text.”
Backward compatibility — the ability of a newer version of a proto schema to correctly read messages serialised by an older version, and vice versa. Maintaining backward compatibility means: never remove or renumber existing fields; use the reserved keyword for retired fields; and add new fields with new field numbers.
“Mark the deprecated field as reserved rather than deleting it — that preserves backward compatibility with old clients.”
“We have a schema compatibility check in CI that fails if anyone removes a field number from a live proto.”
grpc-gateway — a protoc plugin that generates a reverse proxy, translating RESTful HTTP/JSON requests into gRPC calls. It lets you expose a gRPC service to clients that cannot speak HTTP/2 or protobuf, such as browsers or third-party integrations.
“We use grpc-gateway so external partners can call our gRPC services over plain REST without any extra effort.”
“The gateway annotations live in the proto file alongside the service definition — no separate OpenAPI spec to maintain.”
How to Use These in Conversation
Scenario 1 — Code review on a new service
“The proto file looks solid, but the
SearchResponsemessage is missing pagination fields. Also, I’d flip the listing endpoint from unary to server-streaming so the client can render results progressively.”
Scenario 2 — Debugging an outage
“All the errors are
DEADLINE_EXCEEDED— the deadline on the inventory service call is set to 500 ms, which is too tight. Bump it to 2 s and add an interceptor to log slow calls so we can spot this pattern earlier.”
Scenario 3 — Onboarding a new team member
“Start by reading the proto file in the shared-protos repo — that tells you everything the service can do. Run protoc to regenerate the stubs locally, then import the channel from the config package. The auth interceptor is already wired up, so you only need to focus on your business logic.”
Scenario 4 — Architecture discussion
“For the live data feed we need server-streaming rather than polling. We’ll annotate the method in the proto file and add a grpc-gateway endpoint so the frontend team can consume it over SSE until they migrate to a gRPC-Web client.”
Quick Reference
| Term | What it means in plain English |
|---|---|
| Proto file | Schema file describing messages and services |
| Service definition | Declares which remote methods the server exposes |
| Message | Structured data type used for requests and responses |
| Field number | Unique integer identifying a field on the wire — never change it |
| Stub | Auto-generated client code for calling remote methods |
| Channel | Persistent connection between client and server |
| Interceptor | Middleware for logging, auth, tracing, and metrics |
| Deadline | Hard cut-off time after which a call is cancelled |
| Status code | Standardised result code (OK, NOT_FOUND, UNAVAILABLE, etc.) |
| Backward compatibility | Ability of new schema versions to read old messages safely |