---
title: "Integrating Apache APISIX With gRPC-Web - API7.ai"
description: "gRPC Web Introduction Originally developed by Google, gRPC is a high-performance remote ..."
url: "https://api7.ai/blog/integration-with-grpc-web"
---

[Blog](https://api7.ai/blog)

[Products](https://api7.ai/category/products)[Technology](https://api7.ai/category/technology)[Ecosystem](https://api7.ai/category/ecosystem)[Case Study](https://api7.ai/category/usercase)[Team & Community](https://api7.ai/category/community)

Search

⌘ + K

[Blog](https://api7.ai/blog)

Ecosystem

# Integrating Apache APISIX With gRPC-Web

Fei Han

January 25, 2022

[Ecosystem](https://api7.ai/category/ecosystem)

## gRPC Web Introduction

Originally developed by Google, gRPC is a high-performance remote procedure call framework implemented on HTTP/2. However, because browsers do not directly expose HTTP/2, Web applications cannot use gRPC directly. gRPC Web is a standardized protocol that solves this problem.

The first gRPC-web implementation was released in 2018 as a JavaScript library through which Web applications can communicate directly with the gRPC service. The principle is to create an end-to-end gRPC pipeline compatible with HTTP/1.1 and HTTP/2. The browser then sends a regular HTTP request, and a gRPC-Web proxy located between the browser and the server translates the request and response. Similar to gRPC, gRPC Web uses a predefined contract between the Web client and the back-end gRPC service. protocol Buffers are used to serialize and encode messages.

![how gRPC-web works](https://static.api7.ai/2022/10/03/633a423516b37.png?imageMogr2/format/webp)

With gRPC Web, users can call back-end gRPC applications directly using a browser or Node client. However, there are some limitations to using gRPC-Web on the browser side to call gRPC services.

- Client-side streaming and bi-directional streaming calls are not supported.
- Calling gRPC services across domains requires CORS to be configured on the server side.
- The gRPC server side must be configured to support gRPC-Web, or a third-party service agent must be available to translate the call between the browser and the server.

## Apache APISIX gRPC Web Proxy

Apache APISIX supports the proxy of gRPC Web protocol by means of a plug-in, which completes the protocol conversion and data codec work when gRPC Web communicates with gRPC Server in the `grpc-web` plug-in, and its communication process is as follows.

gRPC Web Client -> Apache APISIX (protocol conversion & data codec) -> gRPC server

The following is a complete example showing how to build a gRPC Web Client and proxy gRPC Web requests through Apache APISIX. In the following example, we will use Go as the gRPC Server server handler and Node as the gRPC Web client requestor.

## Configure Protocol Buffer

The first step is to install the Protocol Buffer compiler and related plug-ins.

1. Install `protoc` and `proto-grpc-*`.

   The Protocol Buffer compiler `protoc` and the `protoc-gen-go` and `protoc-gen-grpc-web` plugins for generating Go, JavaScript, and gRPC web interface code for `.proto` need to be installed on your system before writing client and server-side applications.

   Please run the following script to install the above components.

   ```
   #!/usr/bin/env bash

   set -ex

   PROTOBUF_VERSION="3.19.0"
   wget https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOBUF_VERSION}/protoc-${PROTOBUF_VERSION}-linux-x86_64.zip
   unzip protoc-${PROTOBUF_VERSION}-linux-x86_64.zip
   mv bin/protoc /usr/local/bin/protoc
   mv include/google /usr/local/include/
   chmod +x /usr/local/bin/protoc

   PROTO_GO_PLUGIN_VER="1.2.0"
   wget https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v${PROTO_GO_PLUGIN_VER}/protoc-gen-go-grpc.v${PROTO_GO_PLUGIN_VER}.linux.amd64.tar.gz
   tar -zxvf protoc-gen-go-grpc.v${PROTO_GO_PLUGIN_VER}.linux.amd64.tar.gz
   mv protoc-gen-go-grpc /usr/local/bin/protoc-gen-go
   chmod +x /usr/local/bin/protoc-gen-go

   PROTO_JS_PLUGIN_VER="1.3.0"
   wget https://github.com/grpc/grpc-web/releases/download/${PROTO_JS_PLUGIN_VER}/protoc-gen-grpc-web-${PROTO_JS_PLUGIN_VER}-linux-x86_64
   mv protoc-gen-grpc-web-${PROTO_JS_PLUGIN_VER}-linux-x86_64 /usr/local/bin/protoc-gen-grpc-web
   chmod +x /usr/local/bin/protoc-gen-grpc-web
   ```

2. Create the `SayHello` example `proto` file.

   ```
   // a6/echo.proto

   syntax = "proto3";

   package a6;

   option go_package = "./;a6";

   message EchoRequest {
   string message = 1;
   }

   message EchoResponse {
   string message = 1;
   }

   service EchoService {
   rpc Echo(EchoRequest) returns (EchoResponse);
   }
   ```

## Configure the server-side application

1. Generate server-side Go raw messages and service/client stubs.

   ```
   protoc -I./a6 echo.proto --go_out=plugins=grpc:./a6
   ```

2. Implement the server-side handler interface.

   ```
   // a6/echo.impl.go

   package a6

   import (
   "errors"
   "golang.org/x/net/context"
   )

   type EchoServiceImpl struct {
   }

   func (esi *EchoServiceImpl) Echo(ctx context.Context, in *EchoRequest) (*EchoResponse, error) {
   if len(in.Message) <= 0 {
       return nil, errors.New("message invalid")
   }
   return &EchoResponse{Message: "response: " + in.Message}, nil
   }
   ```

3. The server-side application runtime entry file.

   ```
   // server.go
   package main

   import (
   "fmt"
   "log"
   "net"

   "apisix.apache.org/example/a6"
   "google.golang.org/grpc"
   )

   func main() {
   lis, err := net.Listen("tcp", fmt.Sprintf(":%d", 50001))
   if err != nil {
       log.Fatalf("failed to listen: %v", err)
   }

   grpcServer := grpc.NewServer()
   a6.RegisterEchoServiceServer(grpcServer, &a6.EchoServiceImpl{})

   if err = grpcServer.Serve(lis); err != nil {
       log.Fatalf("failed to serve: %s", err)
   }
   }
   ```

4. Compile and start the server-side service.

   ```
   go build -o grpc-server server.go
   ./grpc-server
   ```

## Configure client programs

1. Generate client-side `proto` code.

   Generate client-side JavaScript raw messages, service/client stubs and interface code for gRPC Web's JavaScript.

   The `proto` plugin for gRPC Web provides two modes of code generation.

   1. mode=grpcwebtext: The default generated code sends the payload in grpc-web-text format.

   - Content-type: application/grpc-web-text
   - Payload uses base64 encoding
   - Supports monadic and server streaming calls

   1. mode=grpcweb: send payload in binary protobuf format.

   - Content-type: application/grpc-web+proto
   - Payload is in binary protobuf format
   - Currently only monadic calls are supported

   ```
   protoc -I=./a6 echo.proto --js_out=import_style=commonjs:./a6 --grpc-web_out=import_style=commonjs,mode=grpcweb:./a6
   ```

2. Installing client-side dependencies.

   ```
   npm i grpc-web
   npm i google-protobuf
   ```

3. Execute entry file on client-side.

   ```
   // client.js
   const {EchoRequest} = require('./a6/echo_pb');
   const {EchoServiceClient} = require('./a6/echo_grpc_web_pb');
   // connect to  the entrance of Apache APISIX
   let echoService = new EchoServiceClient('http://127.0.0.1:9080');

   let request = new EchoRequest();
   request.setMessage("hello")

   echoService.echo(request, {}, function (err, response) {
      if (err) {
           console.log(err.code);
           console.log(err.message);
       } else {
           console.log(response.getMessage());
       }
   });
   ```

4. Final project structure

   ```
   $ tree .
   ├── a6
   │   ├── echo.impl.go
   │   ├── echo.pb.go
   │   ├── echo.proto
   │   ├── echo_grpc_web_pb.js
   │   └── echo_pb.js
   ├── client.js
   ├── server.go
   ├── go.mod
   ├── go.sum
   ├── package.json
   └── package-lock.json
   ```

After completing the above steps, you have configured the gRPC Server server application and the gRPC Web client application, and started the server application, which will receive requests on port `50001`.

## Configure Apache APISIX

Next, simply enable the `grpc-web` plugin in the Apache APISIX routing plugin configuration to proxy gRPC web requests.

1. Enable the `grpc-web` proxy plugin.

   Routing must use **prefix matching** (e.g., `/* or /grpc/example/*`), because the gRPC web client passes the package name, service interface name, method name, etc. declared in `proto` in the URI (e.g., `/path/a6.EchoService/Echo`), **using absolute match will prevent the plugin from extracting `proto` information from the URI**.

   ```
   $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
   {
       "uri":"/*", // prefix matching mode
       "plugins":{
           "grpc-web":{} // enable gRPC Web plugin
       },
       "upstream":{
           "scheme":"grpc",
           "type":"roundrobin",
           "nodes":{
               "127.0.0.1:50001":1 // gRPC Server Listen addresses and ports
           }
       }
   }'
   ```

2. Validate gRPC Web Proxy Requests.

   The gRPC Web protocol request can be sent to Apache APISIX by executing `client.js` from Node.

   The above client-side and server-side processing logic are respectively: the client sends a message to the server with the content `hello`, the server receives the message and responds with `response: hello`, and the execution result is as follows.

   ```
   $ node client.js
   response: hello
   ```

3. Disable the `grpc-web` proxy plugin.

   Simply remove the grpc-web attribute from the routing plugin configuration.

   ```
   $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
   {
       "uri":"/*",
       "plugins":{
       },
       "upstream":{
           "scheme":"grpc",
           "type":"roundrobin",
           "nodes":{
               "127.0.0.1:50001":1
           }
       }
   }'
   ```

## Summary

This article brings you hands-on experience about using `grpc-web` in Apache APISIX.

Feel free to start a discussion in [GitHub Discussions](https://github.com/apache/apisix/discussions) or communicate via the [mailing list](https://apisix.apache.org/zh/docs/general/subscribe-guide).

Tags:

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[gRPC-Web](https://api7.ai/tags/grpc-web)

Share article link

Share

Related Posts

[![Why Do Microservices Need an API Gateway](https://static.api7.ai/uploads/2023/02/16/CHqaC3Xw_Ecosystem%20%E6%A8%A1%E6%9D%BF1.png)](https://api7.ai/blog/why-do-microservices-need-an-api-gateway)

## [Why Do Microservices Need an API Gateway](https://api7.ai/blog/why-do-microservices-need-an-api-gateway)

[![Why Do You Need Apache APISIX When Using Amazon Lambda](https://static.api7.ai/uploads/2024/12/25/PGShc0sm_apisix-aws-lambda.png)](https://api7.ai/blog/why-do-you-need-apache-apisix-when-using-amazon-lambda)

## [Why Do You Need Apache APISIX When Using Amazon Lambda](https://api7.ai/blog/why-do-you-need-apache-apisix-when-using-amazon-lambda)

Table of Contents

- [gRPC Web Introduction](#grpc-web-introduction)
- [Apache APISIX gRPC Web Proxy](#apache-apisix-grpc-web-proxy)
- [Configure Protocol Buffer](#configure-protocol-buffer)
- [Configure the server-side application](#configure-the-server-side-application)
- [Configure client programs](#configure-client-programs)
- [Configure Apache APISIX](#configure-apache-apisix)
- [Summary](#summary)

## Related Posts

[![Unlocking Tailored Solutions: Harnessing Apache APISIX and Node-Red in Harmony](https://static.api7.ai/uploads/2024/03/06/uppjizMq_APISIX-node-red-cover.png)](https://api7.ai/blog/apache-apisix-and-node-red)

Ecosystem

March 6, 2024

#### [Unlocking Tailored Solutions: Harnessing Apache APISIX and Node-Red in Harmony](https://api7.ai/blog/apache-apisix-and-node-red)

Combining APISIX and Node-Red can help visually implement a complete request-handling process without rewriting complex code or plugins.

[Node-Red](https://api7.ai/tags/node-red)

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[![WAF & API Gateway Integration: Protecting Your APIs](https://static.api7.ai/uploads/2024/01/29/xV7L0ef7_APISIX_WAF_Cover.jpeg)](https://api7.ai/blog/waf-and-api-gateway-integration)

Ecosystem

January 30, 2024

#### [WAF & API Gateway Integration: Protecting Your APIs](https://api7.ai/blog/waf-and-api-gateway-integration)

By following best practices and deploying the right tools, you can create a robust security layer that protects your APIs from a wide range of attacks.

[WAF](https://api7.ai/tags/waf)

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[![mTLS Everywhere: How to Configure TLS for APISIX](https://static.api7.ai/uploads/2024/12/24/DVhnbLpy_apisix-mtls.png)](https://api7.ai/blog/configure-tls-for-apisix)

Ecosystem

July 31, 2023

#### [mTLS Everywhere: How to Configure TLS for APISIX](https://api7.ai/blog/configure-tls-for-apisix)

Transport Secure Layer, aka TLS, formerly SSL, is among its many pillars of information system security. Let's learn how to configure TLS for the Apache APISIX API Gateway.

[APISIX Basics](https://api7.ai/tags/apisix-basics)

[API Security](https://api7.ai/tags/api-security)
