gRPC vs REST

Most of what gets written about this choice compares numbers a reader has no way to check: gRPC is faster, REST is simpler, pick one. That framing skips the one property of your situation that actually decides it, and it has nothing to do with either technology’s top speed. It is who is going to call the service you have not built yet — a browser, a partner integrating from outside, or a team on the other side of the same deploy pipeline. Answer that first and the rest of the comparison mostly answers itself.

What the contract changes#

Both sides agree on a schema before the first request is sent — a .proto file, compiled into Protocol Buffers. Because the schema is fixed ahead of time, a message on the wire does not need to carry its field names; each field travels as a number the schema already assigns it, and both ends decode the message against the same compiled definition rather than by reading a label off the payload. A REST endpoint carrying JSON makes the opposite trade: the payload is self-describing, so anyone with the URL can read the shape of a response without consulting anything else first.

The schema also produces the client. Instead of a hand-written function that builds a URL, sets headers and parses a body, a team calling a gRPC service compiles the same schema into a client for its own language and calls a method that reads like any other function call. That generated client is where a breaking change gets caught: rename a field or drop a method from the schema, regenerate the client, and the code that referenced the old shape stops compiling — before it ever reaches a caller. A renamed JSON field breaks a REST integration in principle the same way, but nothing forces that discovery before deploy; the first sign is usually a caller’s own parser failing to find a key that used to be there.

# generated from the .proto — field names never travel on the wire
reply = orders_client.GetOrder(GetOrderRequest(order_id="ord-abcde"))

# the REST equivalent — you write the request and trust the shape back
resp = requests.get(f"{base_url}/orders/ord-abcde")
order = resp.json()  # nothing here was checked until this line ran

Same order, two ways of asking for it. The gRPC line calls a method; the REST line still has to build a URL and then trust that whatever comes back has the shape the code expects.

None of this is free. The schema is now a dependency the two teams share at build time as well as at runtime — a service cannot ship a breaking change without its callers regenerating against the new definition, which turns an independent deploy into a coordinated one. gRPC also lets a service configure a retry policy that its generated clients apply automatically: a transient failure can be retried by the client library itself, inside code the calling team never wrote and may never look at. Whether that automatic retry is safe is a question for the server, not the client, and it is the same question idempotency keys and safe retries answers for a retried request generally, whichever protocol produced it.

Who can actually call you#

A browser cannot call a gRPC service directly. gRPC’s messages travel inside HTTP/2 frames and depend on one part of HTTP/2 a browser’s own request APIs do not expose: the trailers that carry a call’s final status after the body has already streamed. Fetch and XMLHttpRequest give a script no way to read them, so a browser talking to a gRPC service needs something in front of it — a proxy, or middleware doing the same job in the same process — translating the call into something the browser can actually send and read. That layer is one more thing to deploy and keep working, not a rounding error.

A partner integrating against an API for the first time is optimising for something different: trying a call before committing engineering time to it. An HTTP endpoint returning JSON can be opened in a terminal, watched in a browser’s network tab, or pasted into a request tool with nothing else installed. A gRPC service asks for the schema and a generated client before the first call can even be shaped — a reasonable ask of a team you already coordinate releases with, and a much larger one of a team still deciding whether to integrate with you at all.

Streaming is where the two stop being close cousins. gRPC defines four kinds of call inside the same model: a single request and response, a stream in either direction alone, and a stream running in both directions over one open call at once. A service that needs to push a sequence of updates to a caller, or exchange messages on both sides of a long-lived call, is using the protocol as it was built rather than bolting something like a WebSocket onto a request-response protocol that was never meant to hold a connection open that way. REST has nothing built in that does the same job; getting the same shape means reaching for a separate mechanism next to it, not inside it.

Choosing the encoding before the caller#

The recurring mistake is picking the encoding first and the situation second. A team compares gRPC’s binary format against JSON, decides the difference is worth having, and adopts gRPC for a service a browser calls a handful of times per page load. The encoding saving is real and it is paid on every call — but a call that happens rarely returns a saving nobody using the product will ever perceive, while the choice still costs everything the previous section named: a proxy layer for the browser traffic, a build-time schema dependency between teams, and a payload nobody can read directly during an incident without the same schema the client was built from.

The tell shows up at the first serious incident: the team spends longer working out what a failing call actually contained — decoding a binary payload against a schema, matching a client version to a service version — than the encoding has saved them in total up to that point. That is not a flaw in gRPC; it is a cost the team accepted for a caller relationship that was never going to pay it back.

Nothing here is an argument against gRPC: the same choice is clearly right one layer down, between two internal services that call each other constantly and already share a release process. The mistake was never the technology — it was reasoning that holds between two internal services and applying it to a caller that is a browser or an outside partner instead. Retries are only one part of what crossing that boundary costs; ordering, partial failure and timeouts are a larger topic than either protocol’s encoding, and the distributed-systems path is the fuller treatment of that ground, on its own terms.