REST to gRPC for Internal Services Blueprint
Move high-volume internal service calls from JSON/REST to gRPC over HTTP/2 with Protobuf contracts. Run both protocols during cutover, gate proto changes in CI, and rely on a mesh for HTTP/2-aware load balancing.
What and Why
Internal service-to-service traffic over JSON/REST carries serialization overhead, weak typing, and no streaming. gRPC uses Protocol Buffers over HTTP/2: compact binary payloads, generated typed clients in every language, bidirectional streaming, and built-in deadlines. For high-volume internal calls this cuts latency and CPU and makes contracts enforceable at compile time.
This blueprint moves east-west (service-to-service) traffic from REST to gRPC while leaving public, browser-facing APIs on REST or GraphQL where gRPC-web is awkward.
Phases
Assessment. Identify internal call paths with the most volume or tightest latency budgets. Confirm both ends are services you control. Public-facing endpoints stay REST.
Contract definition. Write .proto files as the source of truth. Define services, messages, and field numbers with an explicit evolution policy (never reuse field numbers; mark removed fields reserved). Store protos in a shared registry with CI lint and breaking-change detection (buf).
Dual protocol. Run gRPC alongside REST on the same services. Generate stubs for each language. Route a small share of internal traffic over gRPC behind a flag, comparing latency and error rates.
Migration. Move call paths over one at a time. Configure deadlines, retries with backoff, and load balancing (client-side or via service mesh). On Kubernetes, ensure L7 load balancing for HTTP/2 long-lived connections.
Cleanup. Once a path is fully on gRPC, remove the REST handler. Keep REST only where external consumers remain.
Key Risks and Mitigations
- Breaking contract changes: a renumbered field silently corrupts data. Enforce buf breaking-change checks in CI and a strict proto review.
- Skills gap: proto modeling, streaming, and deadline semantics are new. Provide templates and a reference service.
- Load balancing pitfalls: HTTP/2 reuses connections, defeating L4 balancers. Use a service mesh (Istio/Linkerd) or gRPC client-side load balancing.
Recommended Tooling
buf for proto linting, formatting, and breaking-change detection; protoc/grpc plugins for codegen; Istio or Linkerd for mTLS, retries, and HTTP/2-aware balancing; grpcurl for debugging; OpenTelemetry gRPC interceptors for tracing.
Success Metrics
Measure p99 latency and throughput per migrated path against the REST baseline, CPU cost per request, and the number of contract-related production incidents (target zero after CI gating).
Prerequisites
Control of both client and server, HTTP/2-capable infrastructure, a shared proto repository, and agreement on the field-evolution policy before the first contract ships.