API Design

gRPC vs REST: Choosing the Right API Protocol

REST won the public API war because a curl request and a JSON blob are readable by anyone. gRPC exists because inside a company's own service mesh, that readability costs more than it's worth.

Published July 6, 2026

Both are ways for one service to call another over a network, but they optimize for different things. REST optimizes for accessibility: any client that can make an HTTP request and parse JSON can talk to a REST API, no special tooling required. gRPC optimizes for efficiency and type safety between services that both agree to use the same contract up front.

The contract: OpenAPI docs vs .proto files

A REST API's contract is typically described after the fact, or alongside the code, in an OpenAPI/Swagger document. Nothing stops a REST endpoint from silently changing its response shape; discipline about versioning and documentation is entirely on the team.

gRPC starts from a .proto file that defines the service and message shapes before any code exists. That file is the contract, and it generates client and server code in whatever languages you need:

// orders.proto
syntax = "proto3";

service OrderService {
  rpc GetOrder (OrderRequest) returns (OrderResponse);
}

message OrderRequest {
  int64 order_id = 1;
}

message OrderResponse {
  int64 order_id = 1;
  double amount = 2;
  string status = 3;
}

protoc --python_out=. --grpc_python_out=. orders.proto

Running protoc generates the request/response classes and a client stub. Callers get compile-time type checking — passing a string where the schema expects an int64 fails before the code ever runs, not at 2am when a malformed payload hits production. The full syntax for messages, services, and field numbering is laid out in the official Protocol Buffers language guide.

Wire format: JSON text vs binary protobuf

REST typically sends JSON, which is human-readable and trivially inspectable with curl or a browser's network tab. gRPC serializes messages as binary protobuf, which is smaller and faster to parse but opaque without the schema — you can't just eyeball a gRPC payload the way you can a JSON response. That opacity is a real debugging cost that teams underestimate before they adopt gRPC internally.

Transport: HTTP/1.1 vs HTTP/2

REST commonly runs over HTTP/1.1, one request per connection round trip (or pipelined, with caveats). gRPC requires HTTP/2, which multiplexes many concurrent requests over a single TCP connection and supports true bidirectional streaming — a client can keep a stream open and send or receive a sequence of messages rather than one request, one response:

service OrderService {
  rpc StreamOrderUpdates (OrderRequest) returns (stream OrderStatus);
}

That streaming mode has no clean REST equivalent; you'd reach for WebSockets or Server-Sent Events to get similar behavior, layered on top of REST rather than native to it.

Where each one actually fits

gRPC shines for service-to-service calls inside a system you control end to end: microservices talking to each other, where every caller and callee can be regenerated from the same .proto files whenever the contract changes, and where the performance difference (lower latency, smaller payloads, connection reuse) compounds across thousands of internal calls per second. REST shines for anything a third party, a browser, or a public integration needs to consume, where "any HTTP client can call this and read the response" outweighs the efficiency gains, and where the tooling ecosystem — browser dev tools, Postman, straightforward caching via HTTP semantics — is built around request/response JSON rather than binary streams.

A common pattern in practice: gRPC for the internal service mesh, with an API gateway translating to REST/JSON at the edge for external clients. That gives internal services the type safety and performance, while public consumers still get the accessible, cacheable interface REST provides.

Error handling: two different vocabularies

REST APIs typically communicate failure through HTTP status codes — 404 for not found, 409 for conflict, 429 for rate limited — a vocabulary every HTTP client, proxy, and monitoring tool already understands, plus a JSON body with details specific to the API. gRPC defines its own smaller, protocol-level status code set (NOT_FOUND, ALREADY_EXISTS, RESOURCE_EXHAUSTED, and so on) that's consistent across every gRPC service regardless of language, attached to the response as metadata rather than layered on top of HTTP semantics. Debugging a REST error is often as simple as reading the status code in a browser's network tab; debugging a gRPC error usually means reaching for a tool that understands the protobuf schema, since the raw wire response isn't human-readable on its own.

Versioning and evolving the contract

REST APIs version informally — a new URL prefix (/v2/orders), a header, or just adding optional fields to existing JSON responses and hoping clients ignore what they don't recognize. Protobuf builds a compatibility discipline directly into the schema: every field has a unique number, and adding a new field with a new number is safe for old clients (they simply don't see it), while reusing or removing a field number without care breaks every client still compiled against the old .proto. That discipline is a genuine advantage for gRPC when many independent services depend on a shared contract evolving over years, but it only pays off if teams actually follow the numbering rules rather than treating the schema as an afterthought.