Skip to main content

​
Overview

Apinizer WebSocket proxy works exactly the same logic as HTTP APIs. You can route both HTTP and WebSocket requests through the same API Proxy.

​
Basic Concepts

Backend URL

The only required configuration. Specifies the address of your backend WebSocket service.Example: http://backend:9090/ws/api

Relative Path

Works the same logic as HTTP APIs. You can perform flexible routing using wildcards.Examples: /websocket/*, /chat/*

Protocol Conversion

The system automatically performs protocol conversion:
  • http:// → ws://
  • https:// → wss://

​
How It Works?

​
Unified Path Resolve Process

The following example shows how a WebSocket request is processed:
Incoming Request: ws://host/api/websocket/rooms/123?user=john
├─ API Proxy Path: /api/websocket/*
├─ Backend URL: http://localhost:9090/ws/chat
├─ Protocol Conversion: ws://localhost:9090/ws/chat
├─ Remaining Path: rooms/123
└─ Final URL: ws://localhost:9090/ws/chat/rooms/123?user=john
Processing of WebSocket requests goes through the following steps:
1

Query Separation

Query parameters are separated from the request path.
2

Path Normalization

Wildcard signs (*) are cleaned.
3

Remaining Path Calculation

API proxy path is extracted and the remaining path is determined.
4

Protocol Conversion

HTTP → WebSocket protocol conversion is performed (http:// → ws://, https:// → wss://).
5

URL Combination

Final URL is created by combining Backend URL + Remaining Path + Query parameters.

​
Practical Examples

HTTP and WebSocket Unified API Proxy

Routing both HTTP and WebSocket requests through the same API Proxy:Configuration:
  • API Proxy: /api/v1/*
  • Backend URL: http://localhost:8080/service
Example Requests:
  • HTTP: POST /api/v1/users → http://localhost:8080/service/users
  • WebSocket: ws://host/api/v1/chat → ws://localhost:8080/service/chat

Secure Connection (WSS)

Secure WebSocket connection with HTTPS backend:Configuration:
  • API Proxy: /secure/*
  • Backend URL: https://api.example.com/ws
Example Request:
  • WebSocket: ws://host/secure/data → wss://api.example.com/ws/data
When HTTPS backend is used, it is automatically converted to WSS (WebSocket Secure) protocol.

WebSocket Chat Application

WebSocket proxy example for chat application:Configuration:
  • API Proxy: /chat/*
  • Backend URL: http://chat-service:9090/websocket
Example Request:
  • WebSocket: ws://host/chat/room/123 → ws://chat-service:9090/websocket/room/123

​
Frequently Asked Questions

Yes! Both protocols work under the same relative path.
You can route both HTTP and WebSocket requests with the same API Proxy configuration. The system automatically detects the protocol type of the incoming request and processes it appropriately.
Use HTTP or HTTPS. The system automatically converts to WS/WSS.
You can use http:// or https:// protocol in Backend URL. Apinizer automatically performs conversion for WebSocket requests:
  • http:// → ws://
  • https:// → wss://
Yes, all query parameters are transferred to the backend as-is.
Query parameters (?param=value) in WebSocket requests are preserved and transferred to the backend. For example:
ws://host/api/chat/room/123?user=john&token=abc
This request is routed to the backend with query parameters.
1

Go to Environment Settings

Go to the settings of the environment that the API Proxy is connected to.
2

Enable WebSocket Support

Enable WebSocket support from environment settings.
3

Deploy

Deploy the changes. Your existing HTTP API Proxy will now also support WebSocket requests.
No additional configuration is required for your existing HTTP API Proxies. You just need to enable WebSocket support from environment settings.