Banksalad's gRPC Adoption Story: Ensuring Compatibility with a Single Protobuf Repository and grpc-gateway

Background of gRPC Adoption and the Role of Protobuf

In its microservice environment, Banksalad adopted gRPC and Protocol Buffers (protobuf), focusing less on simple performance gains and more on securing a source of truth for API specifications. To solve the problem of documentation becoming outdated and losing trust under the existing REST API and JSON-based communication, they adopted an approach of automatically generating code for each language (Swift, Java, Go, Python, etc.) based on protobuf files.

Single Protobuf Repository (IDL) Strategy

To prevent fragmentation caused by protobuf definitions scattered across services and to improve collaboration efficiency, all protobuf files were consolidated into a single idl repository. This repository manages in git not only the original protobuf files but also the Go, Java, Python, Swagger, and Swift files (gen folder) converted via protoc. This is to prevent inconsistencies in generated output caused by differences in protoc versions, and to block incorrect generation through lint and diff tests at the CI stage.

Compatibility with Existing Services and Use of grpc-gateway

To ensure compatibility between new gRPC services and existing JSON-based REST API services, grpc-gateway was adopted. By importing google/api/annotations.proto into protobuf and adding option (google.api.http), which defines the HTTP method and path, an HTTP layer was configured to face the gRPC layer. This allows existing services to call gRPC services via the JSON API without any changes.

Go Client Implementation and Testing Strategy

When the Go server calls an existing JSON-response service, it uses jsonpb to marshal and unmarshal the request/response into protobuf messages. In particular, the AllowUnknownFields: true option was applied to secure flexibility. For testing, the net/http/httptest module is used to perform error handling and response verification in an environment similar to actual HTTP communication without mocking, and calls between gRPC services were simplified through a client managed with a singleton pattern.