Support for gRPC-JSON Transcoding

[thinkhard-j-park]

Many gRPC services need to be exposed as RESTful JSON APIs to support legacy clients, frontend applications, or public APIs that do not support gRPC natively. Currently, users often have to set up a separate proxy (like Envoy) or use a separate gateway service just to handle this translation.

I would like to propose adding support for gRPC-JSON Transcoding directly within spring-grpc. This feature allows mapping JSON/HTTP requests to gRPC methods using configuration (often via google.api.http annotations in Protobuf).

This concept is well-documented in Google Cloud Endpoints: Transcoding HTTP/JSON to gRPC.

Currently, other ecosystems and frameworks within the Java landscape provide this functionality:

• Armeria: Provides built-in support for serving gRPC and REST/JSON from the same port.
• Spring Cloud Gateway: Offers a JsonToGrpc filter factory to act as a transcoding gateway.

Having native support or a dedicated starter in spring-grpc (e.g., essentially embedded transcoding capability) would greatly simplify the architecture for Spring Boot developers who want to expose their gRPC services over HTTP/JSON without maintaining a separate Gateway component.

[dsyer]

We could certainly do this. I'd be interested to hear from anyone who actually used one of the solutions mentioned above (Spring Cloud Gateway, Envoy, Armeria, Google Cloud ESP) to see how it went, why they did it, and whether it helped at all.

[thinkhard-j-park]

I’d like to share my production experience with both Envoy and Armeria.

We were operating a microservices architecture on Kubernetes. Originally, our services communicated solely via REST. Since a single feature request required an average of three network hops, we faced latency issues. As traffic grew, we needed to improve performance and resource efficiency. However, we couldn't simply replace our massive set of existing production APIs. Therefore, we decided to use gRPC for internal inter-service communication while maintaining the REST interface for external clients via gRPC-JSON transcoding.

Envoy
Initially, we considered using Envoy as an edge service for transcoding. However, we faced challenges customizing the responses—specifically, it was difficult to map the transcoded responses to our legacy API formats or handle compressed REST responses flexibly.

Spring + Armeria
To solve this, we built an edge server using Spring + Armeria to handle the transcoding. Armeria integrates well with Spring and provides robust, production-ready gRPC support. While this solved the customization issues we had with Envoy, it introduced complexity. The team had to master both frameworks, which resulted in a significant learning curve.

In our new project, we use Istio Ingress Gateway (Envoy) for the gRPC-JSON transcoding, while internal servers run on Spring + Armeria. One benefit here is the developer experience: since Armeria natively supports transcoding, developers can test gRPC servers via REST locally without needing to set up a local Istio/Envoy environment.

Eventually, if spring-grpc matures to reliably support features like transcoding, we plan to remove Armeria to simplify our technology stack.

[dsyer]

Thanks for that. I understand the migration scenario, and the "public access over JSON" scenario. Not sure I buy the "local testing" scenario as valuable (grpcurl works great for that, and there's no guarantee that istio will behave the same as ameria).

[thinkhard-j-park]

You're right, the transcoding isn't identical. However, since both rely on the same .proto specs, they work practically the same for most scenarios.

​My point is about development speed: it lets backend engineers build and test rapidly in a local environment without a Gateway, using the actual interfaces clients will use.