How do gRPC and REST differ for internal APIs?
gRPC defines an API as services and methods in .proto files. The protobuf compiler generates client stubs and server interfaces, so a call looks like a local function invocation. Messages are serialized as binary protobuf and sent over HTTP/2, with status codes carried in HTTP/2 trailers rather than the HTTP status line. REST models an API as resources addressed by URLs and manipulated with HTTP methods. Payloads are usually JSON, and a schema is optional: you can publish an OpenAPI document, or the contract can live only in the server code.
The interaction models also differ. REST is request/response against a resource, and streaming needs extra mechanisms such as chunked responses, server-sent events or WebSockets. gRPC has four call types built into the method definition:
- Unary: one request, one response.
- Server streaming: one request, a stream of responses.
- Client streaming: a stream of requests, one response.
- Bidirectional streaming: both sides stream independently on one HTTP/2 stream.
| Dimension | gRPC | REST |
|---|---|---|
| Contract | Required .proto schema |
Optional (OpenAPI or none) |
| Wire format | Binary protobuf | Usually JSON text |
| Transport | HTTP/2 | HTTP/1.1 or HTTP/2 |
| Clients | Generated | Generated or hand-written |
| Streaming | Native, four call types | Add-on mechanisms |
The choice is mostly about when you pay. gRPC costs you up front in schema discipline, code generation and HTTP/2-aware infrastructure. REST is cheaper at the start, and you pay later through contract drift and hand-written clients that disagree with the server.
// orders.proto: one service exposing all four gRPC call types.
// protoc generates client stubs and server interfaces from this file.
syntax = "proto3";
package orders.v1;
message GetOrderRequest { string order_id = 1; }
message Order {
string order_id = 1;
string status = 2;
int64 total_cents = 3;
}
message WatchOrdersRequest { string customer_id = 1; }
message OrderLine { string sku = 1; int32 quantity = 2; }
message UploadSummary { int32 lines_accepted = 1; }
message OrderEvent { string order_id = 1; string note = 2; }
service OrderService {
// Unary: one request, one response.
// Closest REST equivalent: GET /orders/{order_id}
rpc GetOrder(GetOrderRequest) returns (Order);
// Server streaming: one request, a stream of responses.
// REST would need SSE, chunked responses or polling.
rpc WatchOrders(WatchOrdersRequest) returns (stream Order);
// Client streaming: many requests, one response.
// REST usually batches these into one large POST body.
rpc UploadLines(stream OrderLine) returns (UploadSummary);
// Bidirectional streaming: both sides send independently
// on a single HTTP/2 stream. REST typically falls back to WebSockets.
rpc OrderChat(stream OrderEvent) returns (stream OrderEvent);
}
A protobuf service definition that declares all four gRPC call types, with comments showing how each one maps, or fails to map cleanly, onto REST's resource model.
How does a gRPC call work compared with a REST call?
Both protocols ride on HTTP, but they use it differently. Follow one unary call through each to see where they diverge.
A gRPC unary call:
- Application code calls a method on the generated stub, such as
GetOrder, passing a request object and a context that holds the deadline and metadata. - The stub serializes the request to protobuf bytes. Client interceptors run at this point and can add tracing headers, auth tokens or logging.
- The client sends an HTTP/2 request. The method is always
POST, and the path is derived from the service definition:/orders.v1.OrderService/GetOrder. Thecontent-typeisapplication/grpc, and the remaining deadline travels in thegrpc-timeoutheader. - The body is a length-prefixed message: a one-byte compression flag, a four-byte message length, and then the protobuf bytes. Streaming calls send a series of these frames on the same HTTP/2 stream.
- On the server, the gRPC runtime routes by path to the generated service interface. It deserializes the message and calls your handler with a context that carries the deadline and cancellation.
- The response comes back as HTTP headers, zero or more length-prefixed messages, and then trailers containing
grpc-statusand optionallygrpc-message. The HTTP status is normally 200 even when the call fails. The real outcome is in the trailers. - The client stub decodes the message and returns either a typed response or a status error to the caller.
A REST call does the same job with conventions instead of generated code. The client builds a URL and picks an HTTP method, for example GET /orders/123. It serializes any body to JSON, often by hand or through a generated OpenAPI client, and sends it over a pooled HTTP/1.1 or HTTP/2 connection. The server's router matches the method and path, and a handler parses the JSON. The response's HTTP status line carries the outcome. The client then parses a JSON body whose shape it must already know.
The practical difference is what is fixed by the framework and what is left to each team. In gRPC, routing, serialization, error codes, deadlines and cancellation are all part of the protocol and the generated code. In REST, each of those is a choice that teams make per service, and those choices may or may not be consistent across an organization.
Where does latency actually go in an internal API call?
Before choosing a protocol for speed, find out where the time in a call actually goes. Most internal requests spend nearly all of it waiting on a database, a cache or another service.
| Component | What drives it | Does gRPC change it? |
|---|---|---|
| Serialization | Payload size, schema shape, CPU | Yes. Binary protobuf is smaller and cheaper to parse than JSON |
| Connection setup and TLS | New connections per request | Only if REST clients aren't pooling. With keep-alive, both amortize this cost |
| Concurrency per connection | Number of in-flight calls | HTTP/2 multiplexes many calls over one connection |
| Queueing | Saturated threads or pools | No |
| Downstream I/O | Queries, disks, network hops | No |
Illustrative estimate. These inputs are assumptions, not measurements:
- JSON costs 10 µs per KB for encode plus decode. Protobuf costs 3 µs per KB.
- Path A is one 2 KB call in front of a 15 ms query. JSON adds 20 µs and protobuf adds 6 µs. Both are under 0.2% of the latency, so the difference is noise.
- Path B is an aggregator that fans out 40 calls of 100 KB each. That is 4,000 KB per request, which costs about 40 ms with JSON and 12 ms with protobuf. Against a 50 ms budget, serialization now dominates.
- At 500 requests per second, Path B's serialization alone works out to roughly 20 cores of CPU for JSON and 6 for protobuf.
To run this on your own system, benchmark encode and decode with your real payloads. Then multiply by the bytes per call and the calls per request. Compare the result with the downstream spans in your traces. If serialization is a small share, protocol choice won't fix your latency.
Why do long-lived HTTP/2 connections break load balancing?
An L4 load balancer makes one decision per TCP connection. It picks a backend when the connection opens and never looks at what flows through it afterward. With HTTP/1.1 this works reasonably well: each connection carries one request at a time, so clients open pools of many connections, those connections churn, and traffic spreads across backends roughly evenly.
HTTP/2 removes that churn. A gRPC client typically opens one connection per target and multiplexes every request over it for hours. If you have ten client pods and twenty backends, at most ten backends receive traffic. New backends added during a scale-out get nothing until clients reconnect. The symptom is confusing. Aggregate CPU looks fine, but a few instances run hot and their tail latency rises. Autoscaling also adds capacity that sits idle.
There are three common fixes, and each costs something to run:
- L7-aware proxies (a dedicated proxy tier or a sidecar per pod) terminate HTTP/2 and balance individual requests. Balancing is accurate, but every call takes an extra hop, and you now own proxy configuration, upgrades and certificates.
- Client-side balancing uses gRPC's built-in policies, such as round-robin over resolved addresses. The client holds connections to every backend and spreads calls across them. This needs reliable service discovery, often via DNS. Each client language must also be configured correctly, which is easy to get wrong.
- Connection recycling sets a maximum connection age on the server so that clients periodically reconnect and rebalance. It is cheap to deploy, but the balance it produces is coarse. Add jitter and a grace period so that in-flight calls drain instead of failing.
(A) PROBLEM: an L4 LB picks a backend once per TCP connection
+----------+ one HTTP/2 conn, +------+ +-----------+
| client 1 |=====all RPCs========>| |====>| backend 1 | HOT
+----------+ multiplexed for hrs | L4 | +-----------+
+----------+ | LB | +-----------+
| client 2 |=====================>| |====>| backend 2 | HOT
+----------+ +------+ +-----------+
+-----------+
| backend 3 | idle (new)
+-----------+
(B1) FIX: L7-aware proxy or sidecar balances each RPC
+--------+ HTTP/2 +----------+ per-RPC +-----------+
| client |=========>| L7 proxy |---------->| backend N | cost: extra hop,
+--------+ +----------+ +-----------+ config, certs
(B2) FIX: client-side balancing (gRPC round_robin)
+-------------+ ===> backend 1 cost: reliable service discovery
| client: | ===> backend 2 (often DNS), correct config
| round_robin | ===> backend 3 in every client language
+-------------+ (one conn per backend, RPCs rotate across them)
(B3) FIX: server-side max connection age (connection recycling)
+--------+ conn A (max age + jitter) +----+ GOAWAY, grace period
| client |============================>| LB | drains in-flight RPCs,
+--------+ +----+ reconnect as conn B
may land elsewhere
cost: cheap, balance is coarse
Long-lived multiplexed HTTP/2 connections pin all RPCs to whichever backends an L4 balancer chose at connect time, leaving new backends idle; L7 proxies, client-side round-robin, and max-connection-age recycling each restore balance at a different operating cost.
How do protobuf contracts compare with OpenAPI and schemaless REST?
A .proto file is the contract and the input to code generation. Server stubs and client libraries in each language come from the same file, so a contract change shows up as a compile error, not as a runtime surprise. Compatibility rests on field numbers, not names. The binary encoding tags every value with its number, which leads to three rules:
- Never reuse or renumber a field. An old binary still decodes number 4 as the field it used to be.
- Mark removed fields
reserved, by number and by name. The compiler then rejects any later attempt to reuse them. - Avoid type changes that reinterpret bytes. Narrowing
int64toint32truncates values, and switchingint32tosint32changes the varint encoding. Both decode without an error and produce wrong numbers.
If teams follow these rules, old readers skip fields they don't recognise and new readers fall back to defaults. That is why services can be deployed in any order.
OpenAPI-first REST can come close to this, but the spec is often written alongside the handlers and drifts unless CI checks the two against each other. JSON keys act as identifiers, so a rename is a breaking change. Schemaless REST has no machine-checked contract at all.
| Aspect | Protobuf | OpenAPI-first REST | Schemaless REST |
|---|---|---|---|
| Source of truth | .proto file |
Spec, if enforced | Handler code |
| Client generation | Standard | Available, uneven quality | Hand-written |
| Breaking-change detection | Field rules, linters | Spec diffing | Production incidents |
| Error format | Status codes plus details | Whatever the spec defines | Varies by endpoint |
The upfront cost is highest for protobuf. Over time, the bill for schemaless APIs keeps growing: undocumented fields, error shapes that differ by endpoint, and hand-written clients that break without any warning.
// orders.proto, version 2 of the contract.
// Server stubs and clients in every language are generated from this file.
syntax = "proto3";
package orders.v1;
message Order {
// Field 3 ("coupon_code") was removed in v2. Reserving both the number
// and the name makes protoc reject any later attempt to reuse them, so an
// old binary never decodes new data as a coupon code.
reserved 3;
reserved "coupon_code";
string order_id = 1;
// Kept as int64. Narrowing to int32 would truncate large values, and
// switching to sint64 would change the varint encoding. Both still decode
// without an error but yield wrong numbers on mixed-version deployments.
int64 amount_cents = 2;
string customer_id = 4;
// Added in v2 under a fresh number. Old readers skip the unknown field 5;
// new readers that receive v1 data see the default (empty string).
string currency = 5;
// To "rename" a field, change only the name and keep the number. The binary
// wire format uses numbers. Code that uses the field name and JSON mapping
// still treat a rename as a breaking change.
}
A protobuf message evolved safely: the removed field is reserved by number and by name, the integer type stays unchanged, and the new field gets an unused number so old and new services can be deployed in any order.
How should errors, deadlines and streaming be handled?
gRPC gives every call a fixed set of status codes and a deadline carried on the wire in the grpc-timeout header. REST has rich HTTP status codes but no standard way to say how much time the caller has left, so each team adds its own timeout header or relies on per-hop client timeouts that don't add up correctly.
| Concern | gRPC | REST |
|---|---|---|
| Error model | Fixed codes (DEADLINE_EXCEEDED, UNAVAILABLE, RESOURCE_EXHAUSTED) plus optional rich details |
HTTP status plus whatever body shape each endpoint chose |
| Deadline | Sent with the request; the server sees remaining time | Ad hoc header, or none |
| Cancellation | Client cancel propagates to the server context | Connection close, often unnoticed by the handler |
Deadline propagation matters because a call chain has one budget. Suppose service A has 300 ms left and B spends 120 ms. C should then see roughly 180 ms, not its own default of 1 s. In gRPC you get this by passing the incoming context to outgoing calls. When the budget runs out, the whole chain stops work, so no downstream service is left doing work nobody will read.
To approximate this in REST:
- Define one header that carries the remaining milliseconds.
- Subtract elapsed time at each hop.
- Reject work when the budget is already spent.
- Enforce all of this in shared middleware, not in each handler.
Streaming
Streaming fits when a single call must deliver many results over time:
- live updates
- large result sets
- log tailing
It costs more than it looks:
- Retries: A transparent retry is unsafe once responses have been sent.
- Timeouts: A single deadline is wrong for a long-lived stream.
- Backpressure: Flow control only works if handlers actually block on send.
- Load balancing: Long streams pin a client to one backend and resist load shedding.
If a response fits in memory and finishes in seconds, use a unary call or a paginated REST endpoint instead.
import express, { Request, Response, NextFunction } from "express";
const HEADER = "x-deadline-remaining-ms"; // one agreed header, shared by all services
const DEFAULT_BUDGET_MS = 1000; // used only at the edge, when no caller set a budget
const SAFETY_MARGIN_MS = 10; // covers network time the header can't measure
// Shared middleware: turn the incoming budget into an absolute deadline plus one abort signal.
function deadline(req: Request, res: Response, next: NextFunction) {
const raw = req.header(HEADER);
const budget = raw === undefined ? DEFAULT_BUDGET_MS : Number(raw);
if (!Number.isFinite(budget) || budget <= SAFETY_MARGIN_MS) {
res.status(504).json({ error: "deadline already exceeded" }); // reject before doing work
return;
}
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), budget - SAFETY_MARGIN_MS);
// Approximate gRPC cancellation: if the caller disconnects, stop downstream work too.
res.on("close", () => { clearTimeout(timer); if (!res.writableEnded) controller.abort(); });
res.locals.deadlineAt = Date.now() + budget - SAFETY_MARGIN_MS;
res.locals.signal = controller.signal;
next();
}
// Outgoing calls forward the time that is left, not a fresh per-hop timeout.
async function callDownstream(res: Response, url: string) {
const remaining = res.locals.deadlineAt - Date.now();
if (remaining <= 0) throw new Error("budget spent; not calling " + url);
return fetch(url, {
headers: { [HEADER]: String(remaining) },
signal: res.locals.signal, // aborts on deadline or client disconnect
});
}
const app = express();
app.use(deadline);
app.get("/orders/:id", async (req, res) => {
try {
const r = await callDownstream(res, `${process.env.ORDERS_BACKEND_BASE}/orders/${req.params.id}`);
res.status(r.status).json(await r.json());
} catch {
if (!res.headersSent) res.status(504).json({ error: "deadline exceeded" });
}
});
app.listen(8080);
Express middleware that approximates gRPC deadline propagation in REST: it reads a remaining-milliseconds header, rejects requests whose budget is already spent, forwards only the time left to downstream calls, and aborts in-flight work when the deadline passes or the client disconnects.
What does debugging gRPC cost compared with REST?
During an incident, REST payloads can be read directly. An engineer can replay a request with curl, read the JSON in a browser, or grep a packet capture. gRPC frames are length-prefixed protobuf over HTTP/2, so a raw capture shows bytes. Decoding them requires the schema, and the person on call may not have it.
The gRPC toolchain
Enable server reflection on internal services so that grpcurl can list methods, describe messages and send JSON-encoded requests without local .proto files. A reflection endpoint exposes your API surface, so restrict it to internal networks or authenticated callers. For traffic inspection, use a proxy or packet analyzer that can load your descriptors and decode protobuf. Raw TCP dumps will not show you message contents.
Observability parity
Put observability in interceptors and middleware rather than in handlers, and use the same conventions for both protocols:
- Tracing: propagate the same trace-context headers. gRPC metadata carries them like HTTP headers.
- Logging: log the method name, status, deadline remaining and a redacted JSON rendering of the message.
- Metrics: use one label scheme for both protocols. Map gRPC status codes and HTTP status codes into a single dimension so dashboards and alerts cover both.
Build and onboarding cost
Codegen adds a pipeline step. Keep .proto files in one shared repository or package, and generate stubs in CI. Do not commit stubs by hand. Run breaking-change checks on schema changes to catch version skew between services. Check generated-code quality in each language you use, because support varies between languages. Budget onboarding time for engineers who have only worked with REST's tooling, which almost every engineer already knows.
How can gRPC save engineering time?
The time savings come from work that the contract and generated code remove. They do not come from the wire format. The savings are real when many teams consume the same APIs. They shrink toward zero for a single team calling a single service.
Where the time goes back to engineers:
- No hand-written clients. Each consuming team gets a typed client from the
.protofile. Nobody maintains per-language HTTP wrappers, URL builders or JSON mapping code, and nobody has to fix them when the server changes. - Contract breaks surface at build time. A removed method or a changed message type fails compilation in the consumer's CI. Under schemaless REST, the same break shows up as a production error that someone has to trace back to a deploy.
- Breaking-change review is automated. A linter or breaking-change check on
.protodiffs replaces manual review of compatibility questions such as "is it safe to deploy the server first?" - One error and deadline model. Retry logic, timeout handling and alerting can be written once against gRPC status codes and shared across services. Teams don't each reinvent error envelopes and timeout headers, as the REST middleware example above has to.
- Shared cross-cutting code. Auth, tracing, logging and metrics go into interceptors that every service reuses, instead of being reimplemented per framework.
- One contract for several interfaces. The same
.protocan drive internal clients, an HTTP/JSON gateway and API reference documentation, so these don't drift from each other.
Where gRPC costs time back:
- Setting up and maintaining the codegen pipeline and the shared schema repository.
- Load-balancing work for long-lived HTTP/2 connections.
- Debugging without plain-text payloads until reflection and decoding tools are in place.
- Onboarding engineers who know only REST tooling.
Illustrative estimate. All inputs are assumed, not measured:
- Assume 6 consuming teams each spend 2 engineer-days per quarter updating hand-written clients after server changes. That totals 12 engineer-days per quarter. Generated clients reduce this to regenerating and fixing compile errors, assumed here at 0.5 days per team, or 3 days in total.
- Assume 2 incidents per quarter are caused by contract drift, each costing 3 engineer-days to diagnose and fix, for 6 days in total. Assume build-time checks catch most of these before deploy.
- Against that, assume the platform team spends 5 engineer-days per quarter on the codegen pipeline, proxy configuration and tooling.
Under these assumptions, gRPC comes out ahead by roughly 10 engineer-days per quarter. With 1 consuming team and no drift incidents, the same arithmetic gives a net loss. Plug in your own team count, change frequency and incident history before treating gRPC as a time saver.
Who should use gRPC for internal APIs?
gRPC pays off for organizations where the costs it removes are large and the costs it adds can be absorbed by someone who owns them.
Good fits:
- Organizations with many internal services and several languages. Generated clients and one shared contract save the most work when many teams consume each API.
- Teams with a platform or infrastructure group. Someone needs to own the shared
.protorepository, the codegen pipeline, load-balancing configuration, interceptors and debugging tools. - Services on high fan-out or chatty paths. In these paths, serialization cost and per-connection concurrency are a measurable share of latency, as in Path B of the estimate above.
- Systems that need streaming. Examples include live updates, log tailing or bidirectional sessions, where gRPC's native call types replace add-on mechanisms.
- Call chains that depend on deadlines and cancellation. Deep service graphs benefit from deadlines and cancellation that propagate without custom middleware.
Poor fits:
- Small teams with a few services in one language. A well-structured REST API with an enforced OpenAPI spec gives most of the contract benefits with less tooling.
- APIs consumed by browsers, partners or the public. Browsers can't speak native gRPC directly and need gRPC-Web through a proxy or a gateway. External consumers generally expect HTTP/JSON.
- I/O-bound services where latency is dominated by databases or downstream calls. Faster serialization changes little in these services.
- Teams without capacity to run HTTP/2-aware load balancing. Pinned connections will cause uneven load until someone fixes them.
When should you choose gRPC, REST, or both?
Use the call pattern, not raw speed, to decide. gRPC's advantages grow with the number of services, the number of languages and calls per request. REST's advantages grow with the number of humans and outside parties who touch the API.
| Factor | Favours gRPC | Favours REST |
|---|---|---|
| Service count and languages | Many services, polyglot | Few services, one stack |
| Call volume | High fan-out, chatty paths | Low, I/O-bound calls |
| Interaction style | Streaming, bidirectional | Request/response |
| Consumers | Internal code only | Humans, partners, browsers |
| Team size | Platform team owns tooling | Small team, no dedicated support |
When to avoid gRPC
Don't adopt gRPC only for speed when most of each call is spent waiting on a database or downstream service. Faster serialization saves little when it is a small fraction of the total time. You still take on the load-balancing, proxy and debugging costs described earlier. The same applies if your main pain is unclear contracts. A strictly enforced OpenAPI spec with generated clients fixes that without changing the transport.
Running both
Many organizations end up using gRPC between services and REST at the edge. A gateway or transcoding layer maps HTTP/JSON routes onto protobuf methods. This is a reasonable split because one .proto contract drives both interfaces. Count the gateway as a real component, though. It is another hop that adds latency. It is another deployment to patch and scale. It is also another place where errors must be translated, so map gRPC status codes to HTTP statuses deliberately rather than relying on defaults.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to grpc vs rest internal apis, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.