How API Gateways Support WebSocket: Architecture, Implementation, and Best Practices

Introduction

WebSocket is a protocol that enables full-duplex, persistent communication between clients and servers over a single TCP connection. Unlike HTTP, which is stateless and unidirectional, WebSocket provides low-latency, real-time interaction—making it ideal for chat apps, live feeds, collaborative editing, and IoT use cases.

In modern architectures, API gateways serve as the entry point for all client traffic. Supporting WebSocket traffic through an API gateway requires special handling, as it deviates from the request-response model of HTTP. In this article, we explore how API gateways support WebSocket connections, the architectural considerations involved, and best practices for implementation.

What Is WebSocket and Why Is It Different?

WebSocket vs HTTP

WebSocket Handshake

WebSocket starts with an HTTP Upgrade request:

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

If the server supports WebSocket, it responds with:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

After this handshake, the connection is upgraded, and both client and server can send messages independently.

Challenges of Routing WebSocket Through an API Gateway

• Connection Persistence: WebSocket connections can last hours. Gateways must manage long-lived connections efficiently.
• Load Balancing: Unlike stateless HTTP requests, WebSocket sessions must be sticky or forwarded consistently.
• Protocol Upgrade Support: Gateways must understand and support the HTTP Upgrade mechanism.
• Monitoring and Logging: Real-time traffic is harder to inspect than discrete HTTP requests.
• Security and Throttling: Need to enforce policies without breaking real-time flow.

Architecture: WebSocket Through API Gateway

🔁 Flow Diagram: WebSocket Lifecycle in an API Gateway

sequenceDiagram
  participant Client
  participant Gateway
  participant Backend
  Client->>Gateway: HTTP Upgrade Request
  Gateway->>Backend: Proxy Upgrade Request
  Backend-->>Gateway: 101 Switching Protocols
  Gateway-->>Client: 101 Switching Protocols
  Note over Client,Backend: WebSocket Tunnel Established
  Client-->>Backend: WebSocket Frame (Message)
  Backend-->>Client: WebSocket Frame (Reply)

Gateway Responsibilities

• Accept and validate the Upgrade request
• Maintain TCP connection state
• Forward frames between client and backend
• Apply observability and security policies

How Different API Gateways Support WebSocket

Apache APISIX

• Native WebSocket proxying via websocket route option
• Support for routing based on URI, headers, and query params
• Plugin support for rate limiting and auth

Example Configuration:

{
  "uri": "/ws",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "192.168.1.10:8080": 1
    }
  },
  "websocket": true
}

Kong

• WebSocket support is enabled by default
• Works with TCP stream plugin for L4 proxying

Envoy

• Supports WebSocket via use_websocket: true in HTTP connection manager
• Full support for header-based routing

NGINX

• Requires specific config for upgrade headers
• No native awareness of WebSocket—acts as a TCP tunnel

Example Configuration:

location /ws/ {
  proxy_pass http://backend;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "Upgrade";
}

Best Practices for WebSocket in API Gateways

1. Enable Connection Keep-Alives and Timeouts

• Ensure idle connections are dropped after a configurable time.
• Monitor for zombie connections.

2. Use Sticky Sessions if Required

• If the backend is stateful, configure session stickiness.
• Use headers or cookies to enforce routing affinity.

3. Implement Rate Limiting Per Connection

• Prevent abuse by counting messages or bandwidth per client.

4. Apply Authentication on Initial HTTP Upgrade

• JWT or API key validation should happen before the handshake completes.

5. Monitor Connections and Metrics

• Count active WebSocket sessions
• Log handshake failures and abnormal terminations

📊 Monitoring Flow

sequenceDiagram
  participant Client
  participant Gateway
  participant Metrics
  Client->>Gateway: WebSocket Request
  Gateway-->>Metrics: Log Upgrade Attempt
  Gateway-->>Client: 101 Switching Protocols
  Client-->>Gateway: WebSocket Frame
  Gateway-->>Metrics: Log Message Count/Errors

Summary

WebSocket enables a new category of real-time applications. API gateways can support WebSocket traffic, but require careful configuration to handle long-lived connections, preserve performance, and ensure security.

Choose an API gateway that supports native WebSocket routing and integrates metrics and access policies from day one.

FAQ

1. Can WebSocket be secured with TLS through a gateway?

A: Yes. Use wss:// on the client and terminate TLS at the gateway or a dedicated TLS proxy.

2. Does WebSocket work with service meshes like Istio?

Yes, but make sure the mesh proxy (e.g., Envoy) supports connection upgrades and TCP tunnels.

3. How do I test WebSocket endpoints?

Use tools like wscat, browser dev tools, or Postman with WebSocket support.

4. Is load balancing possible with WebSocket?

Yes, but use sticky sessions or consistent hashing for stateful backends.

5. Can I inspect or block specific WebSocket messages?

Most gateways proxy messages blindly. Deep inspection requires additional middleware or L7-aware proxies.

Next Steps

Stay tuned for our upcoming column on the API gateway Guide, where you'll find the latest updates and insights!

Eager to deepen your knowledge about API gateways? Follow our Linkedin for valuable insights delivered straight to your inbox!

If you have any questions or need further assistance, feel free to contact API7 Experts.