Key takeaway
- gRPC explained for architects: how it works over HTTP/2 and protobuf, four call types, gRPC vs REST and WebSocket, gRPC-Web limits and production practice.
What is gRPC?
gRPC is an open-source remote procedure call (RPC) framework in which, as the gRPC introduction puts it, a client application can directly call a method on a server application on a different machine. You define a service and its methods in a .proto file, and generated code gives each language a client stub and a server skeleton.
For architects the short answer is this: gRPC is a contract-first, typed way for services to call each other, usually over HTTP/2 with protocol buffers. It fits internal service-to-service traffic. It is a poor default for public browser APIs, where REST over JSON is simpler. For the wider pattern, see our guides on microservices with Java and Golang and SOA versus microservices.
How does gRPC work?
A gRPC call has four parts. The service contract is written in protocol buffers, the interface definition language. The protoc compiler with a gRPC plugin generates client and server code. A channel, which is a connection to a host and port, carries the calls. Each call ends with a status code and optional trailing metadata.
On the wire, messages are encoded with protocol buffers by default, though the introduction notes other formats such as JSON can be used. gRPC runs over HTTP/2. RFC 9113 describes HTTP/2 as using field compression and multiple concurrent exchanges on one connection, so a blocked or stalled exchange does not stop progress on other streams. That is why one long-lived connection can carry many calls.
What are the four kinds of gRPC call?
| Call type | What happens | Typical fit |
| Unary | One request, one response, like a normal function call | Most lookups and commands |
| Server streaming | One request, then a stream of responses until none remain | Feeds, progress updates, large result sets |
| Client streaming | The client sends a sequence of messages, then the server returns one response | Uploads, batched telemetry |
| Bidirectional streaming | Both sides read and write independent streams; order within each stream is preserved | Interactive sessions, long-running exchanges |
Source for call types: gRPC core concepts. The same page covers deadlines (a call that misses its deadline ends with DEADLINE_EXCEEDED), cancellation (changes made before a cancellation are not rolled back) and metadata (key-value information such as authentication details).
gRPC vs REST: which should you choose?
REST over JSON and gRPC are not rivals for every job. REST is the common choice for public and partner APIs because any HTTP client can call it and tooling is everywhere. gRPC suits internal calls where both ends are under your control and a strict contract matters.
| Question | REST over JSON | gRPC |
| Contract | Optional, for example an OpenAPI description | Mandatory .proto definition and generated code |
| Payload | Text, usually JSON | Protocol buffers by default |
| Transport | Commonly HTTP/1.1 or HTTP/2 | HTTP/2 |
| Streaming | Not part of the basic request-response model | Four call types, including bidirectional |
| Browser use | Direct | Through gRPC-Web and a proxy |
| Best fit | Public and partner APIs | Internal service-to-service calls |
On payload size, the protobuf overview calls protobuf smaller and faster than JSON but gives no benchmark numbers, and it says messages are not compressed by default. It also warns against protobuf for data larger than a few megabytes, for self-describing data, and where a formal standards-body specification is required. Treat any speed-up figure you see elsewhere as something to test in your own environment.
Schema evolution is a real advantage. The same page says you can add and delete fields without breaking existing services if you follow the update rules, and that field numbers should never be reused. For API testing practice on either style, see our guide to API testing.
Where does gRPC fit in a microservices architecture?
In a microservices estate, gRPC is usually used for east-west traffic between services, with a REST or GraphQL layer at the edge for browsers and partners. This also avoids a common mistake of exposing internal gRPC services directly to the internet.
If you build agent-based systems, the same split applies: agents call internal services through typed, deadline-bound calls, while the decision layer above them decides what an agent may call. ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control. See also our guide to agentic workflows.
Video: gRPC adoption and working architecture, from the XenonStack channel.
Does gRPC replace WebSocket?
No. RFC 6455 defines WebSocket as a protocol for two-way communication between a browser-side client and a server, using an opening handshake and then message framing over TCP. It was designed so browser applications need not open multiple HTTP connections. gRPC is a method-call framework with typed contracts. Choose WebSocket for a browser-facing push channel, and gRPC for typed calls between services. gRPC streaming is not a drop-in for a browser socket, because browsers need gRPC-Web.
Can browsers use gRPC?
Through gRPC-Web, a JavaScript client for browsers. According to the grpc-web repository, clients connect through a proxy, with Envoy as the default, unary calls are supported, server-side streaming works only in grpcwebtext mode, and client-side and bidirectional streaming are not currently supported. The gRPC-Web GA announcement is dated 23 October 2018. Check the repository for the current state before you design around streaming.
What should you do in production?
| Area | Guidance from gRPC documentation | Source |
| Connections | Reuse channels and stubs; use keepalive pings to keep HTTP/2 connections alive during inactivity | Performance guide |
| Load balancing | One client's streams travel over a single connection, so an L3/L4 balancer sends them to one backend; use an L7 proxy or client-side balancing | gRPC load balancing |
| Health | A standard health checking service with Check (unary) and Watch (streaming), reporting SERVING or NOT_SERVING | Health checking |
| Errors | Calls end with standard status codes such as UNAVAILABLE and DEADLINE_EXCEEDED | Error handling |
| Security | TLS to authenticate the server and encrypt traffic; optional client certificates; token credentials as metadata | Authentication |
| Streaming | Use streams to optimise the application, not gRPC; streams cannot be load balanced once started and are harder to debug | Performance guide |
When should you not use gRPC?
- Public APIs for third parties who expect plain HTTP and JSON.
- Browser-first applications that need client or bidirectional streaming (gRPC-Web does not currently support them).
- Teams without capacity to manage
.protoversioning and generated code. - Payloads of several megabytes or more, where the protobuf guidance advises against it.
How do you adopt gRPC step by step?
- Pick one internal service pair with a clear contract and a latency or streaming need.
- Write the
.protofile, generate code, and agree field-number rules for changes. - Set deadlines, handle status codes, and add the health checking service.
- Decide on load balancing (L7 proxy or client-side) before traffic grows.
- Secure the channel with TLS and carry credentials in metadata.
- Keep REST at the edge and measure before moving more services.
Conclusion
gRPC gives internal services a typed contract, generated clients in many languages and four call types over HTTP/2. It is a strong fit for service-to-service traffic and a weaker one for public or browser-first APIs. Decide per interface, measure, and keep the contract and security rules in one governed place. Related reading: cloud-native applications and Kubernetes architecture.
To map one service decision your agents should make, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop. ElixirData Context OS keeps governed context, versioned policy and decision traces in one decision layer above AI agents.
Frequently asked questions
Is gRPC faster than REST?
gRPC uses protocol buffers over HTTP/2, and the protobuf documentation describes protobuf as smaller and faster than JSON, without giving benchmark numbers. Real gains depend on payload shape, network and language runtime, so measure your own services before you migrate.
Can browsers call gRPC services directly?
Not directly. gRPC-Web is a JavaScript client for browsers and, according to its repository, connects through a proxy, with Envoy as the default. It supports unary calls, server-side streaming in grpcwebtext mode, and does not currently support client-side or bidirectional streaming.
Does gRPC replace WebSocket?
No. They solve different problems. WebSocket (RFC 6455) gives a browser a two-way channel to a server. gRPC is a typed RPC framework for calling methods between services, with streaming as one of its four call types.
What are the four kinds of gRPC call?
Unary, server streaming, client streaming and bidirectional streaming, as defined in the gRPC core concepts documentation.
Which languages does gRPC support?
The gRPC languages page lists C#/.NET, C++, Dart, Go, Java, Kotlin, Node, Objective-C, PHP, Python, Ruby, Rust and Swift.
How does gRPC handle security?
According to the gRPC authentication guide, it promotes TLS to authenticate the server and encrypt traffic, offers optional client certificates for mutual authentication, supports ALTS on Google Cloud, and lets you attach token credentials as call metadata.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE
