grpc-api

gRPC API Development

Build efficient gRPC services using Protocol Buffers for contract-first API design, with support for unary calls, server streaming, client streaming, and bidirectional streaming.

When to Use

• Building microservices that require high-performance binary communication.
• Defining strict service contracts with Protocol Buffers (.proto files).
• Implementing real-time bidirectional or server-push streaming.
• Creating internal service-to-service APIs in polyglot architectures.
• Optimizing bandwidth in constrained or high-throughput environments.

Critical Patterns

• Contract First: Always define your .proto file before writing any server or client code. The proto IS your API contract.
• Use Proper Status Codes: Map domain errors to gRPC status codes (NOT_FOUND, ALREADY_EXISTS, INVALID_ARGUMENT, etc.). Never return raw exceptions.
• Field Numbering is Forever: Once a proto field number is assigned and released, NEVER reuse it. Add new fields with new numbers; deprecate old ones.
• Streaming for Large Data: Use server streaming for large result sets and client streaming for bulk uploads. Avoid sending massive unary payloads.
• Deadlines Over Timeouts: Always set deadlines on client calls. A missing deadline can hang forever in production.
• TLS in Production: Never use createInsecure() credentials outside of local development.
• Keep Messages Flat: Avoid deeply nested message types. Flatten where possible for better wire efficiency and readability.

Proto Definition Patterns

Complete Service Definition

syntax = "proto3";

package user.service;

message User {
  string id = 1;
  string email = 2;
  string first_name = 3;
  string last_name = 4;
  string role = 5;
  int64 created_at = 6;
  int64 updated_at = 7;
}

message CreateUserRequest {
  string email = 1;
  string first_name = 2;
  string last_name = 3;
  string role = 4;
}

message UpdateUserRequest {
  string id = 1;
  string email = 2;
  string first_name = 3;
  string last_name = 4;
}

message GetUserRequest {
  string id = 1;
}

message ListUsersRequest {
  int32 page = 1;
  int32 limit = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  int32 total = 2;
  int32 page = 3;
}

message DeleteUserRequest {
  string id = 1;
}

message Empty {}

// Four RPC patterns: unary, server streaming, client streaming, bidirectional
service UserService {
  rpc GetUser(GetUserRequest) returns (User);              // Unary
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse); // Unary
  rpc CreateUser(CreateUserRequest) returns (User);        // Unary
  rpc UpdateUser(UpdateUserRequest) returns (User);        // Unary
  rpc DeleteUser(DeleteUserRequest) returns (Empty);       // Unary
  rpc StreamUsers(Empty) returns (stream User);            // Server streaming
  rpc BulkCreateUsers(stream CreateUserRequest) returns (ListUsersResponse); // Client streaming
}