Configure WebSocket Proxying

WebSocket is a communication protocol that provides full-duplex communication channels over a single TCP connection. API7 Enterprise can proxy WebSocket traffic, allowing you to manage real-time, bidirectional communication between clients and your upstream services.

Prerequisites

• An API7 Enterprise instance is running.
• A Gateway Group is created and a Gateway instance is running.
• A token from the Dashboard.

Start a Sample WebSocket Server

Start a sample upstream server with WebSocket support:

docker run -d \
  --name websocket-server \
  -p 8080:8080 \
  jmalloc/echo-server

The server exposes a WebSocket endpoint at /.ws that echoes back any message it receives.

The examples below assume the gateway can reach the Docker host at host.docker.internal. If your environment uses a different host address, replace host.docker.internal with that address.

Enable WebSocket on a Route

WebSocket proxying is enabled on a per-route basis. When enable_websocket is set to true, the Gateway handles the initial HTTP Upgrade handshake and maintains the connection.

Configure a Route for WebSocket

Create or update a Route and set the enable_websocket field to true.

# 1. Create a Service for the WebSocket upstream
curl -k "https://localhost:7443/apisix/admin/services/websocket-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "websocket-service",
    "upstream": {
      "type": "roundrobin",
      "nodes": [
        {
          "host": "host.docker.internal",
          "port": 8080,
          "weight": 1
        }
      ]
    }
  }'

# 2. Create a Route for the Service
curl -k "https://localhost:7443/apisix/admin/routes/websocket-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "websocket-route",
    "paths": ["/.ws"],
    "service_id": "websocket-service",
    "enable_websocket": true
  }'

services:
  - name: websocket-service
    upstream:
      nodes:
        - host: host.docker.internal
          port: 8080
          weight: 1
    routes:
      - name: websocket-route
        uris:
          - /.ws
        enable_websocket: true

adc sync -f adc.yaml

Validate the Configuration

You can test the WebSocket connection using a tool like wscat or curl.

Using wscat

Install wscat via npm:

npm install -g wscat

Then, connect to your WebSocket route:

wscat -c ws://localhost:9080/.ws

If the connection is successful, you can send hello and receive the echoed response.

In the local validation environment, the Admin API example returned 101 Switching Protocols through http://127.0.0.1:9080/.ws.

Using curl

You can also test the initial handshake with curl by providing the required upgrade headers:

curl -i -N -H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Host: localhost" \
-H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
-H "Sec-WebSocket-Version: 13" \
http://localhost:9080/.ws

A successful handshake will return an HTTP/1.1 101 Switching Protocols response.

Next Steps

• Configure gRPC Proxying — learn how to handle gRPC traffic and transcoding.
• Configure GraphQL Proxying — explore GraphQL-aware traffic management.