ADR-003: gRPC Gateway

Status

Accepted

Context

We need to expose our internal gRPC services to web clients that don’t support gRPC directly. We also want to maintain a single source of truth for our API definitions while supporting both gRPC and REST/JSON clients.

Decision

We will use grpc-gateway to automatically generate a RESTful HTTP API from our gRPC service definitions. This allows us to:

• Maintain a single API definition in protobuf
• Support both gRPC and REST clients
• Auto-generate OpenAPI documentation
• Preserve strong typing across the stack

Consequences

Positive

• Single source of truth for API definitions
• Automatic REST API generation from protobuf
• Built-in OpenAPI/Swagger documentation
• Consistent API behavior between gRPC and REST
• Strong typing preserved through code generation

Negative

• Additional build step for gateway generation
• Some gRPC features don’t map perfectly to REST
• Slightly increased complexity in the API layer
• Need to carefully design protos for good REST mappings

Implementation

The grpc-gateway will:

• Run as a reverse proxy in front of gRPC services
• Translate HTTP/JSON requests to gRPC
• Use protobuf annotations for REST endpoint configuration
• Generate OpenAPI specs for documentation