Skip to main content

Version: 3.11.0

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.


REST to gRPC Diagram

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.


API7.ai Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.

Product

API7 Cloud

SOC2 Type IIISO 27001HIPAAGDPRRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation