REST to gRPC for Internal Services Blueprint

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.