API Style & Pattern Comparisons
Side-by-side trade-offs. Neither column wins — the consumer environment, the data shape and the operational budget decide.
REST vs gRPC
Resource-oriented HTTP+JSON for the broadest possible audience vs typed, generated-stub RPC over HTTP/2 for services you control end to end.
Consumers you don't control: browsers, partners, scripts, anything that can speak HTTP and read JSON.
High-frequency internal calls where JSON serialization and text payloads dominate the latency budget.
Ubiquitous tooling, human-readable exchanges, HTTP caching and status semantics for free, zero client codegen required.
Nothing generates or verifies the contract, so docs, server and clients quietly drift apart.
Docs and contract tests carry the whole compatibility burden; payload discipline is manual, endpoint by endpoint.
Internal service-to-service calls where you own both ends, regenerate clients from the proto, and care about per-call overhead.
Browser or third-party consumers — gRPC-Web needs a translating proxy, and debugging needs dedicated tooling.
One proto is the schema, the docs and the client; binary payloads run 5–10x smaller; native streaming and deadline propagation.
A proto change ships without regenerating consumers, or a hop in the path can't speak HTTP/2.
A schema registry, codegen pipelines per language, gRPC-aware load balancing, and interceptors instead of curl for debugging.
| Dimension | REST | gRPC |
|---|---|---|
| Contract source | OpenAPI description, maintained beside the code | The .proto file — schema, docs and clients in one artifact |
| Payload | JSON text; readable, verbose, slower to parse | Protobuf binary; compact and fast, opaque without tooling |
| Browser support | Native — fetch and go | Only via gRPC-Web plus a proxy layer |
| Streaming | Bolted on (SSE, chunked responses) | Unary, server-, client- and bidirectional streaming built in |
| Compatibility discipline | Conventions and review — nothing enforces them | Field numbers and reserved ids make many breaks mechanical to avoid |