> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket API Proxy Creation

> WebSocket proxy routing guide. Works exactly the same logic as HTTP APIs, you can route both HTTP and WebSocket requests through the same API Proxy and perform protocol conversion (http→ws, https→wss)

## Overview

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

## Basic Concepts

<CardGroup cols={3}>
  <Card title="Backend URL" icon="server">
    The only required configuration. Specifies the address of your backend WebSocket service.

    **Example:** `http://backend:9090/ws/api`
  </Card>

  <Card title="Relative Path" icon="route">
    Works the same logic as HTTP APIs. You can perform flexible routing using wildcards.

    **Examples:** `/websocket/*`, `/chat/*`
  </Card>

  <Card title="Protocol Conversion" icon="arrows-rotate">
    The system automatically performs protocol conversion:

    * `http://` → `ws://`
    * `https://` → `wss://`
  </Card>
</CardGroup>

## How It Works?

### Unified Path Resolve Process

<AccordionGroup>
  <Accordion title="Path Resolve Example">
    The following example shows how a WebSocket request is processed:

    ```text theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Path Resolve Steps">
    Processing of WebSocket requests goes through the following steps:

    <Steps>
      <Step title="Query Separation">
        Query parameters are separated from the request path.
      </Step>

      <Step title="Path Normalization">
        Wildcard signs (`*`) are cleaned.
      </Step>

      <Step title="Remaining Path Calculation">
        API proxy path is extracted and the remaining path is determined.
      </Step>

      <Step title="Protocol Conversion">
        HTTP → WebSocket protocol conversion is performed (`http://` → `ws://`, `https://` → `wss://`).
      </Step>

      <Step title="URL Combination">
        Final URL is created by combining Backend URL + Remaining Path + Query parameters.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Practical Examples

<CardGroup cols={3}>
  <Card title="HTTP and WebSocket Unified API Proxy" icon="network-wired">
    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`
  </Card>

  <Card title="Secure Connection (WSS)" icon="lock">
    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`

    <Tip>
      When HTTPS backend is used, it is automatically converted to WSS (WebSocket Secure) protocol.
    </Tip>
  </Card>

  <Card title="WebSocket Chat Application" icon="comments">
    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`
  </Card>
</CardGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can the same API Proxy support both HTTP and WebSocket?">
    <Check>
      Yes! Both protocols work under the same relative path.
    </Check>

    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.
  </Accordion>

  <Accordion title="Which protocol should I use in Backend URL?">
    <Info>
      Use HTTP or HTTPS. The system automatically converts to WS/WSS.
    </Info>

    You can use `http://` or `https://` protocol in Backend URL. Apinizer automatically performs conversion for WebSocket requests:

    * `http://` → `ws://`
    * `https://` → `wss://`
  </Accordion>

  <Accordion title="Are query parameters preserved?">
    <Check>
      Yes, all query parameters are transferred to the backend as-is.
    </Check>

    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.
  </Accordion>

  <Accordion title="How can I make my existing HTTP APIs WebSocket-enabled?">
    <Steps>
      <Step title="Go to Environment Settings">
        Go to the settings of the environment that the API Proxy is connected to.
      </Step>

      <Step title="Enable WebSocket Support">
        Enable WebSocket support from environment settings.
      </Step>

      <Step title="Deploy">
        Deploy the changes. Your existing HTTP API Proxy will now also support WebSocket requests.
      </Step>
    </Steps>

    <Tip>
      No additional configuration is required for your existing HTTP API Proxies. You just need to enable WebSocket support from environment settings.
    </Tip>
  </Accordion>
</AccordionGroup>