Transcode HTTP to gRPC

gRPC is an open-source high performance Remote Procedure Call (RPC) framework based on HTTP/2 protocol. It uses protocol buffers (protobuf) as the interface description language (IDL).

This guide will show you how to use the grpc-transcode plugin with the proto object to transform between RESTful HTTP requests and gRPC requests, as well as their corresponding responses.

Prerequisite(s)

• Install Docker.
• Install cURL to send requests to APISIX for validation.
• Install gRPCurl to send requests to gRPC services for validation.
• Follow the Getting Started tutorial to start a new APISIX instance in Docker.

Deploy an Example gRPC Server

Start an example gRPC server Docker instance quickstart-grpc-example on port 50051:

docker run -d \
  --name quickstart-grpc-example \
  --network=apisix-quickstart-net \
  -p 50051:50051 \
  api7/grpc-server-example:1.0.2

This example gRPC server holds several services, such as echo.EchoService:

echo.proto

syntax = "proto3";

package echo;

service EchoService {
  rpc Echo (EchoMsg) returns (EchoMsg);
}

message EchoMsg {
  string msg = 1;
}

In this example, Echo is a method in EchoService that accepts parameter type string defined in EchoMsg.

Test the gRPC method echo.EchoService.Echo using gRPCurl:

grpcurl -plaintext -d '{"msg": "Hello"}' "127.0.0.1:50051" "echo.EchoService/Echo"

A response similar to the following verifies that the gRPC service is working:

{
  "msg": "Hello"
}

Create a Proto Object to Store Protobuf File

Store the protobuf file echo.proto as a proto object in APISIX with the ID quickstart-proto:

curl -i "http://127.0.0.1:9180/apisix/admin/protos" -X PUT -d '
{
  "id": "quickstart-proto",
  "content": "syntax = \"proto3\";

  package echo;

  service EchoService {
    rpc Echo (EchoMsg) returns (EchoMsg);
  }

  message EchoMsg {
    string msg = 1;
  }"
}'

An HTTP/1.1 201 Created response verifies that the proto object is created successfully.

Enable grpc-transcode Plugin

Create a route with ID quickstart-grpc and enable the plugin grpc-transcode:

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "quickstart-grpc",
  "methods": ["GET"],
  "uri": "/echo",
  "plugins": {
    "grpc-transcode": {
      "proto_id": "quickstart-proto",
      "service": "echo.EchoService",
      "method": "Echo"
    }
  },
  "upstream": {
    "scheme": "grpc",
    "type": "roundrobin",
    "nodes": {
      "quickstart-grpc-example:50051": 1
    }
  }
}'

❶ proto_id: the proto object which defines gRPC services

❷ service: gRPC service echo.EchoService in use

❸ method: gRPC method Echo in use

An HTTP/1.1 201 Created response verifies that the route is created and the plugin grpc-transcode is enabled successfully.

APISIX now transcodes the RESTful HTTP requests received at /echo route to proto requests and forwards them to the upstream gRPC server quickstart-grpc-example to invoke the method echo.EchoService/Echo. Once the gRPC server responds, APISIX transcodes the proto responses back to RESTful HTTP responses for clients.

Test gRPC Services in a RESTful Way

Send an HTTP request to /echo with parameters defined in EchoMsg:

curl -i "http://127.0.0.1:9080/echo?msg=Hello"

A valid response similar to the following verifies that the plugin grpc-transcode works:

{"msg":"Hello"}

Next Steps

See the grpc-transcode plugin doc for more configuration options and examples.

In addition to transcoding HTTP requests to gRPC requests, APISIX also supports gRPC-Web, a variation of the native gRPC protocol, with the APISIX plugin grpc-web.