Connecting gRPC services using a JSON Bridge

Setup your gRPC service to be compatible with Connectors

gRPC is a high-performance, language-agnostic Remote Procedure Call (RPC) framework for building APIs. Apollo Connectors can communicate with gRPC services through a gRPC-to-JSON bridge that handles protocol conversion.

gRPC-JSON transcoding

gRPC-JSON transcoding allows HTTP clients to send JSON/HTTP requests that are transparently mapped to gRPC method calls. It handles:

  • Calling gRPC methods with an HTTP POST request to a path like /com.example.ProductService/GetProduct

  • Converting JSON request bodies to Protocol Buffer request messages

  • Converting Protocol Buffers response messages to JSON

Transcoding solutions

Several tools support gRPC-JSON transcoding:

  • Envoy Proxy: An open-source proxy with built-in support via the grpc_json_transcoder HTTP filter.

  • Google Cloud Endpoints: A managed solution using ESP (Extensible Service Proxy).

  • Custom gRPC gateways: You can build one using libraries like grpc-gateway (for Go) or your own logic.

Connecting transcoded gRPC APIs

After setting up your gRPC JSON bridge, you can call it using Connectors just like any other HTTP API:

GraphQL
1type Query {
2  product(id: ID!): Product
3    @connect(
4      source: "productService"
5      http: {
6        POST: "/com.example.ProductService/GetProduct"
7        body: "productId: $args.id"
8      }
9      selection: """
10        sku
11        title
12        description
13      """
14    )
15}

Limitations

When using gRPC-JSON transcoding, there's an important limitation to keep in mind: Field names become part of your public API. Unlike regular gRPC clients that use field numbers for encoding—allowing you to change field names safely—JSON bridges rely directly on field names. This means you cannot change field names in your protobuf definitions without breaking existing clients that consume the JSON API.
Feedback

Ask Community