gRPC: Schema, Codegen and Streams

gRPC starts from a .proto file: services with operations, messages with numbered fields. From that one file every language generates clients and server stubs, so the contract is not documentation somebody keeps in sync — it is the thing both ends compile (Schema-First vs Code-First). A caller that sends a wrong type does not get a 400 in production; it fails to build. That is the largest single advantage over hand-maintained REST clients, and it is why gRPC's natural home is a fleet of services owned by teams who share a build pipeline.

Messages are serialized as compact binary keyed by field number, not name. On the wire a user_id is a tag and a varint, not "user_id":, which is why payloads are smaller and parsing is cheaper than JSON — measurable on hot internal paths, irrelevant on a partner API that makes ten calls a minute (Payload Size: 20KB, 200KB, 5MB). Transport is HTTP/2: many concurrent calls multiplexed on one connection, header compression, and framing that makes streaming a first-class citizen rather than a long-lived hack (HTTP/2: Streams on One Connection).

Four call shapes fall out of that transport: unary (one request, one response), server streaming (one request, many responses — a large result set or progress events), client streaming (many requests, one response — uploads, telemetry), and bidirectional streaming (both — a chat or a live sync). REST reaches the same shapes only by adding SSE or WebSockets beside it (Streaming APIs: Partial Data as a Contract).

Protobuf's compatibility model is precise and unforgiving. Adding a field with a new number is safe: old clients skip unknown tags, new clients see defaults from old servers. Renaming a field is safe on the wire (names are not serialized) and breaking in generated code. Changing a field's type or reusing a number is silently catastrophic — the old client decodes the new bytes as the old type and gets garbage, not an error. Removing a field requires reserved so the number can never be reused (Removing Fields Without Removing Consumers).

Enums deserve their own warning: a new enum value arriving at an old client decodes to the zero value in proto3, which is why the convention of an _UNSPECIFIED = 0 sentinel exists — without it, "suspended" silently becomes "active" in a client that has never heard of suspension (Enum Evolution: The New Value That Broke Old Clients). None of this is harder than JSON evolution; it is just more explicit, and the explicitness is the point — the rules are checkable by a linter in CI, which JSON contracts rarely get (Backward Compatibility: The Real Rules).

The comparison is decided by the consumer environment, which is why Which API Style Should I Use? asks who calls it first. Browsers cannot speak gRPC natively; gRPC-Web and transcoding gateways bridge the gap at the cost of another component. Third-party developers want curl, readable JSON and docs, and get a binary protocol requiring codegen. Internal fleets want compile-time contracts, small payloads and streaming, and get exactly that. Debuggability shifts too: a REST exchange is readable in any proxy log; a gRPC frame needs tooling to decode — a real cost during incidents.

Performance claims need qualification. gRPC is cheaper per call — less serialization CPU, fewer bytes, multiplexed connections — which matters when a request fans out to twenty internal calls. For a public API dominated by round-trip latency, caching and payload design, REST with a CDN often delivers lower end-to-end latency because gRPC responses cannot be cached by anything between client and server (Caching as a Contract Clause). "gRPC is faster" is true of the call and not necessarily of the system.