REST with JSON is the default for web APIs. It's readable, flexible, and works everywhere. It's also 3-10× slower than gRPC for service-to-service communication, requires manual schema documentation, and has no built-in streaming semantics.
gRPC is the alternative for internal microservices and high-throughput APIs: binary serialization with Protocol Buffers, HTTP/2 multiplexing, bi-directional streaming, and code generation in 12 languages from a single .proto schema. In 2026, gRPC is standard for service meshes, ML inference pipelines, and any internal API where latency and throughput matter.
The Problem: REST at the Wrong Layer
REST over JSON was designed for client-server communication across the public internet — where human readability matters and client diversity is unpredictable. Applied to internal microservice communication, its characteristics become costs:
JSON parsing overhead: Serializing a complex object to JSON and back is 5-10× slower than Protocol Buffer serialization. At 10,000 RPC calls/second, this overhead compounds.
No schema enforcement: REST with JSON has no built-in contract. A service changes a field name; clients break silently. API versioning is manual and inconsistent.
HTTP/1.1 head-of-line blocking: A slow request blocks subsequent requests on the same connection. HTTP/2 multiplexes multiple requests over a single connection — a slow stream doesn't block others.
No streaming: REST request-response is fundamentally single-shot. Real-time streaming (model inference tokens, log tailing, live data feeds) requires workarounds: SSE, WebSockets, or polling.
gRPC solves all four using HTTP/2 as transport, Protocol Buffers as serialization, and code generation to enforce the contract at compile time.
How It Works: Protocol Buffers and Code Generation
The center of gRPC is the .proto file — a language-agnostic schema that defines your service and message types. This single file generates client and server code in Python, Go, Java, TypeScript, Rust, and more.
// payments.proto
syntax = "proto3";
package payments.v1;
option go_package = "github.com/myorg/payments/gen/go/payments/v1;paymentsv1";
// Service definition — the RPC contract
service PaymentService {
// Unary RPC: single request, single response
rpc ChargeCard(ChargeRequest) returns (ChargeResponse);
// Server streaming: single request, stream of responses
rpc StreamTransactions(TransactionStreamRequest) returns (stream Transaction);
// Client streaming: stream of requests, single response
rpc BatchCharge(stream ChargeRequest) returns (BatchChargeResponse);
// Bidirectional streaming: stream in both directions
rpc PaymentChat(stream PaymentMessage) returns (stream PaymentMessage);
}
message ChargeRequest {
string customer_id = 1;
int64 amount_cents = 2;
string currency = 3; // "USD", "EUR", etc.
string idempotency_key = 4; // Prevents double-charges
optional string description = 5;
}
message ChargeResponse {
string transaction_id = 1;
ChargeStatus status = 2;
string processor_reference = 3;
int64 processed_at_unix = 4;
}
enum ChargeStatus {
CHARGE_STATUS_UNSPECIFIED = 0; // proto3: always have a zero value
CHARGE_STATUS_SUCCESS = 1;
CHARGE_STATUS_DECLINED = 2;
CHARGE_STATUS_ERROR = 3;
}
message Transaction {
string id = 1;
string customer_id = 2;
int64 amount_cents = 3;
string currency = 4;
int64 created_at_unix = 5;
}
message TransactionStreamRequest {
string customer_id = 1;
int64 since_unix = 2; // Stream transactions after this timestamp
}
message BatchChargeResponse {
int32 total = 1;
int32 succeeded = 2;
int32 failed = 3;
repeated string failed_idempotency_keys = 4;
}
Generate code:
# Install protoc + gRPC plugins
pip install grpcio grpcio-tools
# Generate Python client and server code from .proto
python -m grpc_tools.protoc \
-I. \
--python_out=./gen/python \
--grpc_python_out=./gen/python \
payments.proto
This generates payments_pb2.py (message types) and payments_pb2_grpc.py (service stubs). When the .proto changes, regenerate — mismatches are caught at import time, not at runtime.
Implementation: Server and Client
Python gRPC Server
import grpc
from concurrent import futures
import payments_pb2
import payments_pb2_grpc
import logging
import time
class PaymentServicer(payments_pb2_grpc.PaymentServiceServicer):
"""Implements the PaymentService defined in payments.proto"""
def ChargeCard(self, request, context):
"""Unary RPC: charge a card and return the result."""
# Validate request
if request.amount_cents <= 0:
context.set_code(grpc.StatusCode.INVALID_ARGUMENT)
context.set_details("amount_cents must be positive")
return payments_pb2.ChargeResponse()
if not request.idempotency_key:
context.set_code(grpc.StatusCode.INVALID_ARGUMENT)
context.set_details("idempotency_key is required")
return payments_pb2.ChargeResponse()
# Check idempotency (deduplication)
existing = idempotency_store.get(request.idempotency_key)
if existing:
return existing # Return cached result — safe to retry
# Process charge
try:
result = stripe_client.charge(
customer=request.customer_id,
amount=request.amount_cents,
currency=request.currency,
)
response = payments_pb2.ChargeResponse(
transaction_id=result.id,
status=payments_pb2.CHARGE_STATUS_SUCCESS,
processor_reference=result.balance_transaction,
processed_at_unix=int(time.time()),
)
idempotency_store.set(request.idempotency_key, response, ttl=86400)
return response
except stripe.CardError as e:
return payments_pb2.ChargeResponse(
status=payments_pb2.CHARGE_STATUS_DECLINED,
)
def StreamTransactions(self, request, context):
"""Server streaming: yield transactions as they occur."""
# Initial backfill of historical transactions
for tx in db.get_transactions(
customer_id=request.customer_id,
since=request.since_unix,
):
if context.is_active(): # Check if client is still connected
yield payments_pb2.Transaction(
id=tx.id,
customer_id=tx.customer_id,
amount_cents=tx.amount_cents,
currency=tx.currency,
created_at_unix=int(tx.created_at.timestamp()),
)
# Subscribe to real-time events
with event_bus.subscribe(f"transactions:{request.customer_id}") as sub:
for event in sub:
if not context.is_active():
return # Client disconnected — stop streaming
yield payments_pb2.Transaction(**event)
def serve():
server = grpc.server(
futures.ThreadPoolExecutor(max_workers=10),
options=[
('grpc.max_receive_message_length', 4 * 1024 * 1024), # 4MB
('grpc.max_send_message_length', 4 * 1024 * 1024),
('grpc.keepalive_time_ms', 30000), # Send keepalive every 30s
('grpc.keepalive_timeout_ms', 5000), # Wait 5s for keepalive ack
]
)
payments_pb2_grpc.add_PaymentServiceServicer_to_server(PaymentServicer(), server)
server.add_insecure_port('[::]:50051')
server.start()
logging.info("gRPC server started on port 50051")
server.wait_for_termination()
Python gRPC Client with Interceptors
import grpc
from grpc import UnaryUnaryClientInterceptor
class AuthInterceptor(UnaryUnaryClientInterceptor):
"""Adds authorization header to every outbound RPC."""
def __init__(self, token_provider):
self.token_provider = token_provider
def intercept_unary_unary(self, continuation, client_call_details, request):
metadata = list(client_call_details.metadata or [])
metadata.append(('authorization', f'Bearer {self.token_provider()}'))
metadata.append(('x-request-id', generate_request_id()))
new_details = client_call_details._replace(metadata=metadata)
return continuation(new_details, request)
class RetryInterceptor(UnaryUnaryClientInterceptor):
"""Retries failed RPCs with exponential backoff for retriable status codes."""
RETRIABLE_CODES = {grpc.StatusCode.UNAVAILABLE, grpc.StatusCode.DEADLINE_EXCEEDED}
def intercept_unary_unary(self, continuation, client_call_details, request):
for attempt in range(3):
response = continuation(client_call_details, request)
try:
return response.result()
except grpc.RpcError as e:
if e.code() in self.RETRIABLE_CODES and attempt < 2:
time.sleep(0.1 * (2 ** attempt)) # 100ms, 200ms backoff
continue
raise
# Build client with interceptors
channel = grpc.intercept_channel(
grpc.secure_channel('payments.internal:50051', grpc.ssl_channel_credentials()),
AuthInterceptor(token_provider=get_service_token),
RetryInterceptor(),
)
stub = payments_pb2_grpc.PaymentServiceStub(channel)
# Unary call with deadline
try:
response = stub.ChargeCard(
payments_pb2.ChargeRequest(
customer_id="cust_123",
amount_cents=4999,
currency="USD",
idempotency_key="order_789_charge_1",
),
timeout=5.0, # 5-second deadline
)
print(f"Charged: {response.transaction_id}")
except grpc.RpcError as e:
print(f"RPC failed: {e.code()}: {e.details()}")
The Four Streaming Modes
gRPC's most distinctive feature over REST is native streaming. The four modes cover all communication patterns:
# Mode 1: Unary — request/response (same as REST)
response = stub.ChargeCard(request, timeout=5.0)
# Mode 2: Server streaming — one request, many responses
# Use case: tail a log, stream ML inference tokens, real-time feeds
def stream_inference_tokens(prompt: str):
request = InferenceRequest(prompt=prompt, max_tokens=512)
for chunk in stub.StreamInference(request):
yield chunk.token # Streams as LLM generates
# Mode 3: Client streaming — many requests, one response
# Use case: batch operations, file upload in chunks
def batch_charge(charges: list[ChargeRequest]) -> BatchChargeResponse:
def generate_charges():
for charge in charges:
yield charge
return stub.BatchCharge(generate_charges())
# Mode 4: Bidirectional streaming — both sides stream simultaneously
# Use case: real-time bidirectional chat, agent/tool call loops
async def payment_chat(messages):
async def request_iterator():
for msg in messages:
yield PaymentMessage(text=msg)
async for response in stub.PaymentChat(request_iterator()):
print(f"Server: {response.text}")
For LLM inference APIs, server streaming is the critical mode: instead of waiting for the entire response before returning (4-30 seconds for long responses), the client receives tokens as they're generated. This is how ChatGPT, Claude, and every production LLM API works at the protocol level.
gRPC in Service Meshes: Istio and Envoy
Service meshes like Istio and Linkerd use Envoy as a sidecar proxy. Envoy has first-class gRPC support: health checking, load balancing, observability, and circuit breaking all work at the gRPC protocol level.
# Istio VirtualService: route 10% of gRPC traffic to new version
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: payments-service
spec:
hosts:
- payments.internal
http:
- match:
- headers:
grpc-method: # Route specific gRPC methods differently
exact: "/payments.v1.PaymentService/ChargeCard"
route:
- destination:
host: payments-service
subset: v2
weight: 10 # 10% to new version
- destination:
host: payments-service
subset: v1
weight: 90
Envoy also handles retries for gRPC. The key difference from HTTP retries: gRPC has built-in status codes that indicate whether a request is safe to retry. UNAVAILABLE and DEADLINE_EXCEEDED are typically safe; ALREADY_EXISTS and FAILED_PRECONDITION are not.
# Istio DestinationRule: retry policy for gRPC services
apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
name: payments-retry
spec:
host: payments.internal
trafficPolicy:
connectionPool:
http:
h2UpgradePolicy: UPGRADE # Force HTTP/2 for gRPC
outlierDetection:
consecutive5xxErrors: 5
interval: 10s
baseEjectionTime: 30s
retryPolicy:
attempts: 3
perTryTimeout: 2s
retryOn: "5xx,gateway-error,reset,connect-failure,retriable-4xx"
gRPC vs REST: When to Use Which
| Dimension | gRPC | REST/JSON |
|---|---|---|
| Serialization speed | Binary (~10× faster) | Text (flexible) |
| Schema enforcement | Compile-time (Protobuf) | Optional (OpenAPI) |
| Streaming | Native (4 modes) | Workaround (SSE/WS) |
| Browser support | Limited (grpc-web proxy) | Native |
| Human readability | Low (binary) | High |
| Tooling maturity | Good, growing | Excellent |
| Use case fit | Internal services, ML inference | Public APIs, browser clients |
gRPC is the right choice for:
- Internal microservice communication (service mesh)
- ML model inference (streaming token output, batch inference)
- High-throughput data pipelines
- Polyglot teams needing type-safe cross-language contracts
REST is the right choice for:
- Public APIs consumed by browsers and third parties
- APIs where human readability and curl-debuggability matter
- Simple CRUD services with low traffic
Reflection and Debugging
REST APIs are debuggable with curl. Binary gRPC is not. Two tools bridge this gap:
grpcurl — curl for gRPC:
# List available services (requires reflection enabled on server)
grpcurl -plaintext localhost:50051 list
# Describe a service
grpcurl -plaintext localhost:50051 describe payments.v1.PaymentService
# Call an RPC
grpcurl -plaintext -d '{
"customer_id": "cust_123",
"amount_cents": 4999,
"currency": "USD",
"idempotency_key": "test-001"
}' localhost:50051 payments.v1.PaymentService/ChargeCard
Evans — interactive gRPC REPL:
evans --host localhost --port 50051 --reflection repl
# > call ChargeCard
# customer_id (TYPE_STRING) => cust_123
# amount_cents (TYPE_INT64) => 4999
# ...
To enable server reflection (needed by grpcurl/Evans):
from grpc_reflection.v1alpha import reflection
# Add to your server setup
SERVICE_NAMES = (
payments_pb2.DESCRIPTOR.services_by_name['PaymentService'].full_name,
reflection.SERVICE_NAME,
)
reflection.enable_server_reflection(SERVICE_NAMES, server)
Enable reflection only in non-production environments. Reflection exposes your entire API schema — useful for dev/staging, a security concern in production.
Production Considerations
Health Checking and Load Balancing
gRPC has a standard health checking protocol. All production gRPC servers should implement it — load balancers and service meshes (Istio, Linkerd) rely on it:
from grpc_health.v1 import health_pb2_grpc, health_pb2
from grpc_health.v1.health import HealthServicer
# Add health service to your server
health_servicer = HealthServicer()
health_pb2_grpc.add_HealthServicer_to_server(health_servicer, server)
# Mark service as serving (or NOT_SERVING during graceful shutdown)
health_servicer.set(
"payments.v1.PaymentService",
health_pb2.HealthCheckResponse.SERVING
)
gRPC-Gateway for REST Compatibility
Sometimes you need both: gRPC for internal services and REST for external clients. grpc-gateway generates a REST proxy from your proto annotations:
import "google/api/annotations.proto";
service PaymentService {
rpc ChargeCard(ChargeRequest) returns (ChargeResponse) {
option (google.api.http) = {
post: "/v1/charges"
body: "*"
};
}
}
The gateway translates JSON REST requests into gRPC calls transparently — one server implementation, two transports.
Metadata and Custom Headers
gRPC metadata is the equivalent of HTTP headers — key-value pairs sent with each RPC call. Use metadata for authentication, request tracing, and custom context:
# Server: extract metadata from incoming context
class PaymentServicer(payments_pb2_grpc.PaymentServiceServicer):
def ChargeCard(self, request, context):
# Extract metadata (like HTTP headers)
metadata = dict(context.invocation_metadata())
request_id = metadata.get('x-request-id', 'unknown')
auth_token = metadata.get('authorization', '')
# Verify token
if not verify_token(auth_token):
context.set_code(grpc.StatusCode.UNAUTHENTICATED)
context.set_details("Invalid or missing authorization token")
return payments_pb2.ChargeResponse()
# Add response metadata (like response headers)
context.send_initial_metadata([
('x-request-id', request_id), # Echo back for correlation
('x-processing-region', 'us-east-1'),
])
return process_charge(request)
Interceptors (shown earlier) are the idiomatic way to add metadata globally, rather than in every service method.
Deadlines Are Mandatory
Every gRPC call should have a deadline. Without one, a slow upstream can hold connections indefinitely:
# Always set a timeout — never make an unbounded RPC call
try:
response = stub.ChargeCard(request, timeout=3.0) # 3 seconds max
except grpc.RpcError as e:
if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
# Timeout — circuit break or return cached result
...
Set deadlines based on your SLO, not generously. A 30-second deadline on a 200ms call means slow cascading failures propagate for 30 seconds instead of failing fast.
Performance: Why gRPC Is Faster Than REST
The performance advantage comes from three compounding factors:
Binary serialization vs JSON: JSON is human-readable text. "amount_cents": 4999 encodes as 21 bytes. The same int64 in protobuf encodes as 3 bytes (field tag + varint). For complex nested messages with repeated fields, protobuf is typically 5-10× smaller than JSON.
import json
import time
from google.protobuf import json_format
# Benchmark: serialize 1000 ChargeRequest messages
charge = {"customer_id": "cust_abc123", "amount_cents": 4999, "currency": "USD", "idempotency_key": "idem_xyz789"}
# JSON serialization: ~1,200 nanoseconds per message
json_bytes = json.dumps(charge).encode() # 83 bytes
# Protobuf serialization: ~120 nanoseconds per message
proto_msg = ChargeRequest(**charge)
proto_bytes = proto_msg.SerializeToString() # 34 bytes
# 2.4× smaller, 10× faster serialization
HTTP/2 multiplexing: HTTP/1.1 connections handle one request at a time. Multiple requests require multiple connections (or pipelining with head-of-line blocking). HTTP/2 multiplexes many streams over one TCP connection. At 10,000 RPC/s, the connection overhead difference is significant.
Connection reuse: gRPC clients maintain a pool of long-lived HTTP/2 connections. REST clients often open a new connection per request (or maintain a pool with HTTP keep-alive). Long-lived HTTP/2 connections eliminate TCP and TLS handshake overhead per request.
Combined: in benchmarks of internal service-to-service communication, gRPC typically shows 2-7× lower latency and 2-5× higher throughput than REST/JSON for equivalent payloads. The gap widens with larger payloads and higher concurrency.
Protocol Buffers: Field Numbers and Backward Compatibility
One of protobuf's most important properties: backward-compatible schema evolution. Field numbers — not names — identify fields in the serialized binary. This means you can rename fields without breaking existing clients, and you can add new fields without breaking old clients.
// Version 1 of ChargeRequest
message ChargeRequest {
string customer_id = 1;
int64 amount_cents = 2;
string currency = 3;
string idempotency_key = 4;
}
// Version 2: BACKWARD COMPATIBLE additions
message ChargeRequest {
string customer_id = 1;
int64 amount_cents = 2;
string currency = 3;
string idempotency_key = 4;
optional string description = 5; // New field — old clients ignore it
optional string merchant_id = 6; // Another new field
// NEVER reuse field numbers 1-4 — would break existing serialized data
}
Rules for safe proto evolution:
1. Never delete a field — mark it reserved and add to the reserved list instead
2. Never reuse a field number — the binary format uses numbers, not names
3. New fields should be optional — required fields in proto3 don't exist; in proto2, adding a required field is a breaking change
4. Never change a field type — int32 to int64 might work, but int64 to string will break
5. Never rename an enum value — enum values have both a number and a name; changing the name changes the default serialized value
// SAFE: reserve removed fields to prevent accidental reuse
message OldChargeRequest {
reserved 5, 6; // These field numbers can never be reused
reserved "coupon_code", "promo_id"; // These names can never be reused
string customer_id = 1;
int64 amount_cents = 2;
}
This makes gRPC schema evolution safer than REST JSON APIs. A JSON API change that renames a field silently breaks all clients. A protobuf rename is invisible to the wire format — old and new clients interoperate without modification.
Conclusion
gRPC's advantages are clearest in internal service-to-service communication: binary serialization that's 5-10× faster than JSON, schema enforcement that catches breaking changes at compile time, native streaming for ML inference and real-time data, and code generation that eliminates hand-written client boilerplate.
The ecosystem has matured to the point where gRPC is no longer an exotic choice. Kubernetes, Envoy, Istio, and most cloud-native infrastructure speak gRPC natively. ML frameworks (TensorFlow Serving, Triton Inference Server) use gRPC for inference APIs. The service mesh ecosystem depends on gRPC for control plane communication.
For teams building new internal services in 2026, the decision framework is simple: if it's a browser-facing public API, use REST. If it's a service talking to another service, start with gRPC. The tooling (grpcurl, Evans, reflection), the generated clients, and the schema-first development workflow are all production-ready.
The migration path from existing REST services isn't all-or-nothing. grpc-gateway lets you expose both REST and gRPC from the same server implementation — add gRPC for new service-to-service consumers while maintaining the REST API for existing browser clients. Over time, internal consumers migrate to gRPC; the REST endpoint remains for compatibility. This hybrid approach is how most organizations transition their internal API surface to gRPC without a big-bang rewrite.
The learning curve — proto files, code generation, lack of curl debuggability — is real but small. The payoff at scale is significant. Use REST for public-facing APIs where browser clients and human readability matter. Use gRPC everywhere internal, especially in service meshes where the efficiency gains multiply across thousands of calls per second.
The proto-first workflow also improves cross-team collaboration. Service contracts live in a shared proto repository. Teams consume the generated clients without needing to understand server internals. API reviews become proto reviews — structured, diff-able, and enforceable in CI. This is the developer experience improvement that, more than raw performance numbers, drives gRPC adoption in mature engineering organizations.
Sources
- gRPC — Official documentation (Protocol Buffers, interceptors, health checking)
- Protocol Buffers — Language guide and style guide
- Google Cloud — API Design Guide: gRPC vs REST considerations
- CNCF — gRPC project page and ecosystem
- grpc-gateway documentation
About the Author
Toc Am
Founder of AmtocSoft. Writing practical deep-dives on AI engineering, cloud architecture, and developer tooling. Previously built backend systems at scale. Reviews every post published under this byline.
Published: 2026-05-19 · Written with AI assistance, reviewed by Toc Am.
Get These In Your Inbox
Weekly deep-dives on AI engineering, no fluff. Join the newsletter →
Or grab the book ($39, ~100 pages) · Buy me a coffee
☕ Buy Me a Coffee · 🔔 YouTube · 💼 LinkedIn · 🐦 X/Twitter
