From 2d1837ec71015f197cf1c90b3700dcf9184c072b Mon Sep 17 00:00:00 2001 From: badnikhil Date: Thu, 25 Jun 2026 04:12:38 +0530 Subject: [PATCH] added docs --- doc/user_guide/mqtt_user_guide.md | 411 +++++++++++++++++++++++++ doc/user_guide/websocket_user_guide.md | 381 +++++++++++++++++++++++ 2 files changed, 792 insertions(+) create mode 100644 doc/user_guide/mqtt_user_guide.md create mode 100644 doc/user_guide/websocket_user_guide.md diff --git a/doc/user_guide/mqtt_user_guide.md b/doc/user_guide/mqtt_user_guide.md new file mode 100644 index 0000000000..dca967c798 --- /dev/null +++ b/doc/user_guide/mqtt_user_guide.md @@ -0,0 +1,411 @@ +# Using MQTT in API Dash + +This guide explains how to connect to an MQTT broker, subscribe to topics, and publish messages in API Dash. We'll start from zero and walk through every option in plain language with step-by-step instructions, examples, and tips. + +Use this page when you want to test or interact with an MQTT broker — for example IoT devices, sensors, or any real-time publish/subscribe messaging system — instead of sending one-off HTTP requests. + +> MQTT is different from HTTP. Instead of sending a request and waiting for a single response, you open a long-lived connection to a **broker**, **subscribe** to topics you care about, and **publish** messages to topics. Messages flow in both directions and appear live as they arrive. + + + +--- + +## Where to find MQTT + +1. Create a new request (or open an existing one). +2. Find the request type / protocol selector (the same switcher you use to pick HTTP, GraphQL, or AI) and choose **MQTT**. +3. The request now switches into MQTT mode: + - The **URL field becomes the Broker URL** (it shows a `mqtt://...` placeholder). + - Where the HTTP method dropdown normally sits, you'll now see an **MQTT Version** selector. + - The blue action button reads **Connect** instead of **Send**. + +Once you're in MQTT mode, everything you need lives in the request tabs (**Message**, **Topics**, **Properties**, **Auth**, **Settings**) and the live message log in the response pane. + +--- + +## MQTT at a glance + +- **Broker URL** — the address of the MQTT broker you connect to. +- **MQTT Version** — choose **MQTT 3.1.1** or **MQTT 5.0** (default: MQTT 5.0). +- **Connect / Disconnect** — open or close the connection. +- **Topics tab** — the list of topics you want to subscribe to (receive messages from). +- **Message tab** — type and publish a message to a topic. +- **Properties tab** — custom key/value metadata (MQTT 5.0 only). +- **Auth tab** — username and password for the broker. +- **Settings tab** — port, Client ID, Keep Alive, QoS, TLS, WebSocket, Last Will, and session options. +- **Message log** — the live event stream in the response pane, showing every message sent and received. + +Each section below explains what an option is, when to use it, and exactly how to fill it in. + +--- + +## Quick start + +This is the fastest way to see MQTT working end to end using a free public broker. + +1. Create a new request and set its type to **MQTT**. +2. In the **Broker URL** field, enter a public test broker, for example `broker.hivemq.com` or `broker.emqx.io`. +3. Click **Connect** (or press **Enter** in the Broker URL field). The button changes to **Disconnect** and the status dot in the log turns green. +4. Go to the **Topics** tab and add a topic filter, for example `apidash/test/hello`. Tick its checkbox so it's enabled. +5. Go to the **Message** tab. In **Send to topic:**, enter the same topic (`apidash/test/hello`), type a message in the payload box (for example `Hello MQTT`), and click **Publish**. +6. Watch the **message log** in the response pane. You'll see your message echoed as a sent entry, and because you're subscribed to that topic, you'll also see it arrive back as a received message. +7. When you're done, click **Disconnect**. + +> Tip: Publishing to a topic you're also subscribed to is the easiest way to confirm the whole round trip works. Once that succeeds, you know your connection, subscription, and publishing are all healthy. + +--- + +## Choosing your MQTT version + +The **MQTT Version** selector sits where the HTTP method dropdown normally appears (right next to the Broker URL). + +- **MQTT 3.1.1** — the most widely deployed version. Use it if your broker or devices only support 3.1.1, or if you want the simplest setup. +- **MQTT 5.0** — the newer version with extra features: user properties, request/response metadata, detailed reason codes, and fine-grained session control. **This is the default.** + +When you switch versions, API Dash shows or hides the version-specific options automatically (this is called progressive disclosure — you only see what applies to your chosen version). Specifically, the **Properties** tab and several MQTT 5.0 fields appear only when you select MQTT 5.0. + +> If you're not sure which to pick, start with the default (MQTT 5.0). Most modern public brokers support it. If you hit trouble connecting, switch to MQTT 3.1.1. + +--- + +## Connecting to a broker + +### Broker URL + +- **What it is:** the hostname or IP address of the MQTT broker. +- **When to use it:** always — it's how API Dash knows where to connect. +- **UI label:** the main URL field (placeholder `mqtt://...`). + +Steps: +1. Make sure the request type is **MQTT**. +2. Type the broker address into the URL field (for example `broker.hivemq.com`). +3. Click **Connect**, or simply press **Enter** while your cursor is in the field. + + + +### Connect and Disconnect + +- The action button reads **Connect** when you're disconnected. +- While connecting, the status shows a **connecting** state. +- Once connected, the button changes to **Disconnect** and the status dot turns **green**. +- Click **Disconnect** at any time to close the connection. + +When you connect, API Dash automatically subscribes to all the enabled topics in your **Topics** tab, so you start receiving messages right away. + +--- + +## Connection settings + +Open the **Settings** tab to fine-tune how API Dash connects. Sensible defaults are filled in, so for most public brokers you can connect without changing anything here. + +| Setting | UI label | Default | What it does | +|---|---|---|---| +| Port | Port | 1883 | The network port on the broker to connect to. | +| Client ID | Client ID | auto-generated | A unique name identifying your client to the broker. | +| Keep Alive | Keep Alive (s) | 60 | Seconds between heartbeat pings that keep the connection alive. | +| Default QoS | Default QoS | 0 | The delivery guarantee used for all your subscribes and publishes. | + +### Port + +- **What it is:** the broker's network port. +- **Default:** `1883` (the standard plain-text MQTT port). +- **Auto-remapping:** when you turn on certain options, API Dash automatically updates the port for you so it matches the transport you chose: + +| You enable… | Port becomes | +|---|---| +| Use TLS | 8883 | +| Use WebSocket | 8083 | +| Use TLS **and** WebSocket | 8084 | + +> You can always override the port manually if your broker uses a non-standard one. + +### Client ID + +- **What it is:** a unique identifier for your connection. Brokers use it to track your session. +- **When to set it:** leave it blank and API Dash generates one for you automatically (something like `apidash_` followed by a timestamp). Set your own only if your broker requires a specific Client ID, or if you want to resume a session later. + +### Keep Alive (s) + +- **What it is:** how often (in seconds) API Dash sends a small heartbeat ping so the broker knows you're still there. +- **Default:** `60`. Lower it for flaky networks; raise it to reduce traffic on stable ones. + +### Default QoS + +QoS (Quality of Service) controls the delivery guarantee for your messages. The **Default QoS** dropdown applies to both the topics you subscribe to and the messages you publish. + +| QoS | Name | Meaning | +|---|---|---| +| 0 | At most once | Fire and forget. Fastest, but a message may be lost. **(Default)** | +| 1 | At least once | The broker acknowledges delivery. A message may arrive more than once. | +| 2 | Exactly once | A full handshake guarantees the message arrives exactly once. Slowest. | + +> For interactive testing, QoS 0 is usually fine. Use QoS 1 or 2 only when you specifically need delivery guarantees. + +--- + +## Authentication + +Open the **Auth** tab to send a username and password to the broker. + +- **What it is:** credentials some brokers require before they'll accept your connection. +- **When to use it:** only if your broker is protected. Leave both fields blank for anonymous (open) brokers like the public test brokers. +- **UI labels:** **Username** and **Password** (the password is masked as you type). + +Steps: +1. Open the **Auth** tab. +2. Enter your **Username** and **Password**. +3. Connect as usual. + + + +> Most public test brokers don't require credentials, so you can skip this tab when getting started. + +--- + +## Transport & Security + +In the **Settings** tab, expand the **Transport & Security** section to control how the connection is encrypted and tunneled. + +### Use TLS + +- **UI label:** **Use TLS** — "Encrypt the connection (TLS/SSL)". +- **Default:** off. +- **What it does:** encrypts the connection between you and the broker. +- **When to use it:** whenever your broker offers a secure endpoint, and always in production. + +Turning this on automatically bumps the port from `1883` to `8883` (the standard secure MQTT port). + +### Allow Invalid Certificates + +- **UI label:** **Allow Invalid Certificates** — "Accept self-signed / untrusted certs". +- **Default:** off. +- **Visibility:** this toggle only appears when **Use TLS** is on (it has no meaning otherwise). +- **What it does:** tells API Dash to trust the broker even if its certificate is self-signed or not issued by a recognized authority. +- **When to use it:** for test brokers that use self-signed certificates — a common example is `test.mosquitto.org` on its secure port. + +> Warning: Only enable this for testing. Accepting invalid certificates removes a key security protection, so never use it against a production broker. + +### Use WebSocket + +- **UI label:** **Use WebSocket**. +- **Default:** off. +- **What it does:** tunnels the MQTT connection over a WebSocket transport instead of a raw TCP connection. +- **When to use it:** when your broker only exposes a WebSocket endpoint, or when a firewall blocks raw MQTT ports. + +Turning this on automatically adjusts the port to `8083` (or `8084` if TLS is also on). + +--- + +## Last Will & Testament (LWT) + +In the **Settings** tab, expand the **Last Will & Testament (LWT)** section. + +- **What it is:** a message you register up front that the broker will publish **on your behalf** if your client disconnects unexpectedly (for example, the network drops or the app crashes). +- **When to use it:** to let other clients know when your client goes offline ungracefully — for example, publishing an "offline" status to a topic other devices watch. + + Will | Retain Will | off | If on, the broker keeps the will message as the last message on the topic for future subscribers. | + +Steps: +1. Open the **Settings** tab and expand **Last Will & Testament (LWT)**. +2. Enter a **Will Topic** (for example `clients/myclient/status`). +3. Enter a **Will Message** (for example `offline`). +4. Optionally raise **Will QoS** or turn on **Retain Will**. +5. Connect. The broker now holds your will and publishes it automatically if you drop unexpectedly. + + + +--- + +## Session control (Clean Start & Session Expiry) + +How API Dash handles your session depends on the MQTT version you chose. + +### MQTT 3.1.1 + +There's nothing to configure. API Dash connects with a clean session every time, meaning the broker doesn't keep any state for you between connections. + +### MQTT 5.0 + +In the **Settings** tab you'll see a **Clean Start** toggle. + +- **UI label:** **Clean Start** — "Session ends on disconnect". +- **Default:** on. +- **What it does (when on):** your session is discarded the moment you disconnect — a fresh start every time. + +If you turn **Clean Start off**, a new field appears: + +- **UI label:** **Session Expiry (s)**. +- **Default:** `3600` (one hour). +- **What it does:** tells the broker how many seconds to keep your session (including your subscriptions and any queued messages) after you disconnect, so you can reconnect and resume where you left off. + +> To resume a session later, turn **Clean Start off**, set a **Session Expiry** long enough for your needs, and reconnect with the **same Client ID**. + +--- + +## Subscribing to topics + +Open the **Topics** tab to choose which topics you want to receive messages from. This is a table where each row is one topic filter. + +Each row has: +- An **enable/disable checkbox** — tick it to subscribe, untick it to unsubscribe. +- A **Topic filter** text field — the topic (or wildcard pattern) you want to listen to. +- A **remove button** — deletes the row. + +Adding rows: +- Start typing in the empty last row and a new blank row appears automatically. +- Or click **Add Topic** to add a row manually. + +Steps: +1. Open the **Topics** tab. +2. Type a topic into a row, for example `home/living-room/temperature`. +3. Make sure the row's checkbox is ticked. +4. Repeat for as many topics as you like. + + + +### Wildcards + +Topic filters support MQTT wildcards so you can match many topics at once: + +| Wildcard | Meaning | Example | Matches | +|---|---|---|---| +| `+` | Single level | `home/+/temperature` | `home/living-room/temperature`, `home/bedroom/temperature` | +| `#` | Multi level (must be last) | `sensors/#` | `sensors/temp`, `sensors/humidity/outdoor`, and everything below `sensors/` | + +> Wildcards work only in subscriptions (the Topics tab), never when publishing. When you publish, you must use a full, specific topic. + +### Live subscription behavior + +The Topics tab reacts immediately while you're connected: + +- **Tick a topic** → API Dash subscribes to it right away. +- **Untick a topic** → API Dash unsubscribes immediately. +- **Edit a topic** → API Dash resubscribes with the new filter. + +If you're **not** connected, your topics are simply remembered and subscribed automatically the next time you **Connect**. + +All subscriptions use the **Default QoS** from the Settings tab. + +--- + +## Publishing a message + +Open the **Message** tab to send a message to a topic. + +Fields: +- **Send to topic:** — the full topic you're publishing to. As you type, API Dash suggests topics you're already subscribed to (a convenience only; you can type any topic). +- **Message payload** — a multiline text box for the message body. +- **Retain** toggle — if on, the broker stores this message as the last message on the topic, so future subscribers receive it immediately when they subscribe. +- **Publish** button — sends the message. + +Steps: +1. Open the **Message** tab. +2. Enter a topic in **Send to topic:** (for example `apidash/test/hello`). +3. Type your message in the payload box. +4. Optionally turn on **Retain**. +5. Click **Publish**. + + + +> The **Publish** button is enabled only when you are **connected** and have entered a topic. If it's greyed out, check that you've connected and typed a topic. + +Every message you publish is echoed into the message log as a **sent** entry, showing the payload and topic, so you have a record of what you sent. + +--- + +## MQTT 5.0 extras + +These options appear only when the **MQTT Version** is set to **MQTT 5.0**. + +### User Properties + +Open the **Properties** tab (visible only for MQTT 5.0). + +- **What it is:** custom key/value metadata pairs, similar to HTTP headers, attached to your connection and to the messages you publish. +- **When to use it:** to send extra context — like a trace ID, a source name, or routing hints — without putting it inside the message body. +- **UI:** a table where each row has an **enable checkbox**, a **Key** field, a **Value** field, and a **remove** button. + +Steps: +1. Switch the MQTT Version to **MQTT 5.0**. +2. Open the **Properties** tab. +3. Add a row, enter a **Key** and **Value** (for example `trace-id` → `abc-123`). +4. Make sure the row's checkbox is ticked. +5. Connect and/or publish — the enabled properties are sent along. + + + +> Only rows that are **enabled** and have a **non-empty key** are actually sent. Blank or unticked rows are ignored. + +### Request / Response & Expiry + +In the **Message** tab, expand the collapsible section titled **Request / Response & Expiry (v5)**. + +> Use **Response Topic** and **Correlation Data** together when you want a request/response style exchange: publish a request that tells the responder where to reply and includes a token, then match the incoming reply by that same token. + +### Reason codes + +With MQTT 5.0, the broker returns detailed diagnostic **reason codes** for connection and subscription events. API Dash surfaces these in the message log, so after you connect, subscribe, or disconnect you'll see entries such as a successful CONNACK, a SUBACK granting QoS 1, or a normal-disconnection DISCONNECT. These are a big help when debugging why a broker rejected a connection or subscription. + +--- + +## The message log + +The response pane shows a **live event stream** — a running log of everything that happens on the connection. + +What you'll see: +- **Connection events** — for example "Connected to broker", per-topic "Subscribed to topic: …", and "Disconnected from broker". +- **Every message sent and received**, each with a **direction icon** (so you can tell sent from received), a **timestamp** in `HH:MM:SS` format, and the **payload**. +- **Received messages** also show a **`Topic: `** badge so you know which topic they arrived on. + +Things you can do in the log: + +- **Copy a payload** — tap any message to copy its payload to your clipboard. You'll see a "Copied to clipboard" confirmation. +- **Expand long messages** — messages longer than 300 characters are shortened, with an expand toggle to see the full text. +- **Search** — use the search box to filter messages by payload text (case-insensitive). +- **Filter by topic** — add topic filters as chips (press **Enter** to add each one) to narrow the log to specific topics. These filters support wildcards, just like subscriptions. +- **Clear the log** — click the red **✕** button to empty the log. + +> The log holds up to a maximum number of events, controlled by the **Max Log Messages** app setting. Older entries are dropped once you reach the limit, which keeps memory usage in check during high-volume streams. + +--- + +## Connection lifecycle at a glance + +API Dash shows your connection status with a colored dot and the action button label: + +Typical log entries you'll see: +- On connect: **"Connected to broker: \"** followed by **"Subscribed to topic: …"** for each enabled topic. +- On disconnect: **"Disconnected from broker"**. +- On failure: **"Connection failed: \"** with the reason. + +Click **Disconnect** whenever you want to close the connection. + +--- + +## Public test brokers + +These free brokers are handy for trying things out without setting up your own. None of them require a username or password for the plain (non-TLS) ports. + +| Broker | Address | Plain port | TLS port | Notes | +|---|---|---|---|---| +| HiveMQ | `broker.hivemq.com` | 1883 | 8883 | Open public broker. | +| EMQX | `broker.emqx.io` | 1883 | 8883 | Supports MQTT 5.0. | +| Mosquitto | `test.mosquitto.org` | 1883 | 8883 | The TLS port uses a self-signed certificate — enable **Allow Invalid Certificates**. | + +> These are shared public brokers used by many people. Don't publish anything sensitive to them, and expect to see other people's traffic if you subscribe to broad wildcards like `#`. + +--- + +## Troubleshooting & tips + +- **Can't connect?** Check that the **Port** matches your transport. If you turned on **Use TLS**, the port should be the secure one (usually 8883); for plain connections use 1883. API Dash auto-remaps the port for you when you toggle TLS or WebSocket, but a manually entered port can get out of sync. +- **TLS connection fails with a certificate error?** If you're using a test broker with a self-signed certificate (like `test.mosquitto.org` on its secure port), turn on **Allow Invalid Certificates** under Transport & Security. Don't use this in production. +- **Connected but not receiving messages?** Confirm the topic in your **Topics** tab is enabled (checkbox ticked) and matches what's being published. Double-check your wildcards (`+` matches one level, `#` matches everything below). Also verify the publisher and your subscription are using a compatible QoS. +- **Publish button greyed out?** You must be **connected** and have a topic typed in **Send to topic:** before you can publish. +- **Want to resume a session after disconnecting (MQTT 5.0)?** Turn **Clean Start off**, set a **Session Expiry** long enough to cover your downtime, and reconnect with the **same Client ID**. +- **Broker rejected your connection (MQTT 5.0)?** Read the **reason code** in the message log — it usually tells you exactly why (bad credentials, not authorized, etc.). +- **Log filling up too fast?** Use the **search box** or add **topic filter chips** to focus on what matters, and use the **clear (✕)** button to reset. If you regularly handle high-volume streams, adjust **Max Log Messages** in the app settings. + +--- + +You're set! Pick MQTT, enter a broker, Connect, subscribe in the Topics tab, publish in the Message tab, and watch your messages flow through the live log. diff --git a/doc/user_guide/websocket_user_guide.md b/doc/user_guide/websocket_user_guide.md new file mode 100644 index 0000000000..9fb56b5fe0 --- /dev/null +++ b/doc/user_guide/websocket_user_guide.md @@ -0,0 +1,381 @@ +# Using WebSockets in API Dash + +This guide explains how to use WebSockets in API Dash. WebSockets keep a single connection open so you and a server can send messages back and forth in real time — unlike a normal request, where you ask once and get one answer back. + +Use this page when you need a live, two-way connection: chat apps, live price feeds, multiplayer games, notifications, streaming data, or any service that pushes updates to you as they happen. + + + +--- + +## Quick start + +The fastest way to see WebSockets working is to connect to a public "echo" server, which simply repeats back whatever you send it. + +1. Create a new request (or open an existing one) and switch its type to **WebSocket** (see "Where to find WebSocket" below). +2. In the URL field, enter: + ``` + wss://echo.websocket.org + ``` +3. Click **Connect** and wait for the button to turn into a red **Disconnect**. +4. Open the **Message** tab, type any text — for example `Hello!` — and click **Send**. +5. Watch the live log on the right: you'll see your message go out (↑) and the same text come back (↓) from the echo server. + +That's the whole loop: connect, send, receive. Everything else in this guide builds on those steps. + + + +--- + +## Where to find WebSocket + +WebSocket is a request **type** in API Dash, just like a regular HTTP request. You switch a request to it rather than opening a separate screen. + +1. Create a new request, or select an existing one in the sidebar. +2. Change the request's type to **WebSocket**. +3. The request now shows a teal **WS** badge in the sidebar so you can spot it at a glance. + +Once a request is a WebSocket request, the screen changes to match: there is no HTTP method dropdown (GET/POST/etc.), just a URL field and a **Connect** button. + +> Tip: The teal **WS** badge is your quick visual cue. If you ever can't tell whether a saved request is a WebSocket, look for that badge in the sidebar. + + + +--- + +## WebSockets at a glance + +- **One open connection.** Connect once and keep the line open instead of sending separate requests. +- **Two-way messaging.** You can send messages and the server can send messages, at any time, in any order. +- **`ws://` and `wss://` URLs.** Plain or encrypted endpoints (more on this below). +- **No HTTP method.** Just a URL and a Connect/Disconnect button. +- **Four tabs:** Message, Params, Headers, and Settings. +- **A live event log.** Sent and received messages, plus connection events, stream into the response pane as they happen. +- **Reusable message Templates.** Save common payloads (like a login or ping message) and reuse them across sessions. +- **Keep-alive and auto-reconnect options** for connections that need to stay healthy on flaky networks or behind proxies. + +Each section below explains what these are, when to use them, and exactly how to use them in API Dash. + +--- + +## The WebSocket request screen + +When a request is set to WebSocket, the screen has a few key parts. + +**The URL field** + +This is where you enter the WebSocket endpoint. It accepts addresses that start with `ws://` or `wss://`, for example: + +``` +wss://echo.websocket.org +ws://localhost:8080/chat +``` + +The field shows a hint when empty: *"Enter WebSocket endpoint like wss://echo.websocket.org"*. + +You can also use environment variables in the URL, such as `{{WS_URL}}`. API Dash replaces the variable with its value before connecting, which is handy for switching between development and production servers without retyping the address. + +**The action button** + +There is a single action button next to the URL, and its label tells you the connection state: + +**The four tabs** + +The request area below the URL has four tabs: + +- **Message** — type and send messages, and access saved Templates. +- **Params** — query-string values added to the URL before connecting. +- **Headers** — custom headers sent when the connection is first established. +- **Settings** — advanced options like auto-reconnect and keep-alive pings. + +**`ws://` vs `wss://` — which do I use?** + +The difference mirrors `http` vs `https`: + +| Prefix | Encrypted? | Use it when | +| --- | --- | --- | +| `ws://` | No (plain text) | Local testing, or a server that doesn't support encryption | +| `wss://` | Yes (TLS) | Anything over the public internet, especially with tokens, passwords, or private data | + +> Tip: When in doubt, use `wss://`. It's the secure choice and works for almost every public service. + + + +--- + +## Connecting & disconnecting + +Connecting opens the live line to the server. Here's the full flow. + +1. Enter your `ws://` or `wss://` URL. +2. (Optional) Set up Params, Headers, and Settings first — these are applied at the moment you connect, so configure them *before* clicking Connect. +3. Click **Connect**. The button changes to **Connecting…** and the response pane shows a connecting spinner while the handshake happens. +4. **On success:** the connection is live, the message log appears, and the button turns into a red **Disconnect**. A "Connected" event is added to the log. +5. **To close the connection:** click **Disconnect**. The connection closes normally and the log records *"Disconnected by user"*. + +**If the connection fails** + +If the handshake doesn't succeed (wrong URL, server down, blocked by a firewall, etc.), API Dash logs the error with details and the button returns to **Connect** so you can fix the address and try again. + +> Tip: Connection details such as Params and Headers only take effect at connect time. If you change them while connected, disconnect and reconnect to apply the new values. + + + +--- + +## Params tab + +The **Params** tab lets you add query-string values to the URL, which are tacked on before the connection is made. + +What this is: extra name/value pairs appended to your URL as `?name=value&name2=value2`. Many servers read these to pick a room, pass a token, set a language, and so on. + +When to use it: when the server expects information in the URL itself — for example `?token=abc&room=lobby`. + +How it works in API Dash: +- Each row has a **name** and a **value**, plus an **enable checkbox** so you can keep a parameter saved but turned off. +- Use the **add-param** button to add another row. +- Values support environment variables (like `{{TOKEN}}`). +- The parameters are applied at handshake time — i.e., when you click Connect. + +Steps: +1. Open the **Params** tab. +2. Click the add-param button to create a row. +3. Enter a **name** (e.g., `room`) and a **value** (e.g., `lobby`). +4. Make sure the row's checkbox is ticked so it's included. +5. Add more rows as needed. +6. Click **Connect**. API Dash appends them to your URL, e.g. `wss://example.com/chat?token=abc&room=lobby`. + +> Tip: Untick a parameter's checkbox to temporarily exclude it without deleting it — useful while testing which values a server needs. + + + +--- + +## Headers tab + +The **Headers** tab lets you send custom HTTP headers when the connection is first established. + +What this is: header name/value pairs sent during the WebSocket handshake (the brief HTTP request that opens the connection). + +When to use it: when a server checks headers before letting you in — most commonly authentication, like `Authorization: Bearer `, or a custom header such as `X-Custom-Header`. + +How it works in API Dash: +- Each row has a **name** and a **value**, plus an **enable checkbox**. +- Use the **add-header** button to add another row. +- Headers are applied at handshake time — i.e., when you click Connect. + +Steps: +1. Open the **Headers** tab. +2. Click the add-header button to create a row. +3. Enter a header **name** (e.g., `Authorization`) and **value** (e.g., `Bearer your-token-here`). +4. Make sure the row's checkbox is ticked. +5. Click **Connect**. + +> Tip: Some servers don't check headers during the handshake — instead they expect you to authenticate **after** you connect, by sending your credentials in your very first message. If headers aren't working for login, send an auth message instead (see "Sending messages" and "Templates" below). + + + +--- + +## Settings tab + +The **Settings** tab holds advanced options that help your connection stay healthy. All of these are optional — leave them off if you don't need them. + +### Auto Reconnect + +- **What it is:** Automatically reconnects when the server closes the connection. +- **When to use it:** On flaky networks, or with servers that drop connections periodically, so you don't have to click Connect again every time. +- **Default:** OFF. +- **What you'll see:** When a live connection drops, API Dash retries automatically and logs each try as a *"Reconnection attempt"*. + +Steps: +1. Open the **Settings** tab. +2. Turn the **Auto Reconnect** toggle ON. +3. Connect as usual. If the connection drops, API Dash reconnects on its own. + +### WebSocket Heartbeat + +- **What it is:** Sends periodic keep-alive "pings" to the server. +- **When to use it:** When something between you and the server — like a load balancer or proxy — tends to kill connections that look idle. The regular pings keep the line looking active. +- **Default:** OFF. +- **Good to know:** These pings happen quietly at the protocol level. They do **not** appear in your message log, so they won't clutter it. + +Steps: +1. Open the **Settings** tab. +2. Turn the **WebSocket Heartbeat** toggle ON. +3. (Optional) Adjust the **Ping Interval** below. +4. Connect as usual. + +### Ping Interval (seconds) + +- **What it is:** How often the keep-alive ping is sent, in seconds. +- **When to use it:** Only relevant when **Heartbeat** is ON. Lower it if connections still drop; raise it to reduce traffic. +- **Default:** 30 seconds. +- **Important:** A change to the interval takes effect on your **next** connect. Changing it while you're already connected has no effect until you disconnect and reconnect. + +Steps: +1. Make sure **WebSocket Heartbeat** is ON. +2. Set **Ping Interval (seconds)** to the number of seconds you want (default is 30). +3. Connect (or reconnect, if you changed it mid-session) to apply the new interval. + +> Tip: If you don't know what interval to use, start with the default of 30 seconds and only lower it if your connection still gets dropped while idle. + + + +--- + +## Sending messages + +You send messages from the **Message** tab. This is the main place you'll work once you're connected. + +**The message input** + +A large, multi-line input box (shown in a monospace/code font) with the hint *"Enter message to send…"*. You can type plain text or JSON — whatever your server expects. + +**The Send button** + +- Click **Send** to send the contents of the box as a single text message. +- The input clears after sending, ready for your next message. +- **Send is disabled until you're connected** — connect first, then send. +- Each message you send appears in the log as an outgoing entry, marked with an up arrow (↑). + +> Note: Messages are sent as **text** (send JSON or plain text). Sending binary files/frames from the UI is not supported. + +Steps: +1. Connect to your server. +2. Open the **Message** tab. +3. Type your message or JSON into the input box. +4. Click **Send**. +5. Check the live log on the right to see it go out (↑), and any reply come back (↓). + +### Recently Sent + +Just below the input is a **Recently Sent** strip — a horizontal, scrollable list of roughly your last 10 sent messages for this session. + +- Click any item to **refill the input** with that message, so you can resend or tweak it. +- This is great for quickly repeating a command without retyping it. + + + +### Templates + +For messages you use over and over — a login payload, a subscribe command, a ping — use **Templates**. Open them with the **Templates** button (it has a bookmark icon). + +What templates are: reusable, saved message payloads (typically JSON). API Dash ships with a few defaults to get you started, such as **Ping Message**, **Auth Message**, and **Binance BTC**. Your own templates are saved and stay available across sessions. + +What you can do with templates: +- **Search** the list to find a template quickly. +- **Use** a template to load its payload into the message input. +- **Create a new template:** choose **Create New Template**, then fill in a **Template Name** and a **JSON Payload** in the dialog. +- **Edit** or **delete** an existing template. +- **Save as template:** store whatever is currently in your message input as a new reusable template. + +Steps to create and use a template: +1. Click the **Templates** button (bookmark icon). +2. Choose **Create New Template**. +3. Enter a **Template Name** (e.g., `Login`) and your **JSON Payload**. +4. Save it. It now appears in your templates list. +5. Later, open Templates, pick it from the list to load it into the input, adjust if needed, and click **Send**. + +> Tip: Templates are perfect for servers that authenticate **after** connecting — save your login/auth message as a template and send it as your first message every time you connect. + + + +--- + +## Receiving messages — the live log + +Everything that happens on the connection appears in the **live message log** in the response pane. It's a full-height, auto-scrolling list with the **oldest at the top and newest at the bottom**, so the latest activity is always in view. + +Before you connect, the log shows an empty state: *"No messages yet. Connect to start."* + +**What each entry shows** + +Every line in the log has a small icon (its direction or type), a timestamp in `[HH:MM:SS]` format, and the message payload. The payload text is selectable and shown in a monospace font. + + +**Automatic system events** + +You don't have to log connection activity yourself — API Dash does it for you. The log automatically records events like: connected, each message sent, each message received, *"Connection failed"* (with details), *"Disconnected by user"*, *"Reconnection attempt"*, and when the connection closes. + +**Long messages — expand/collapse** + +If a payload is very long (more than ~300 characters), it's truncated to keep the log tidy, with a **Show More / Show Less** toggle so you can expand or collapse the full text on demand. + +**Copying a message** + +Click any entry to copy its payload to your clipboard. A *"Copied to clipboard"* confirmation appears. + +**Filtering the log** + +Use the **Filter messages…** box to show only entries whose payload contains your search text. The filter is case-insensitive, and a clear (✕) button appears while a filter is active so you can reset it quickly. + +**Clearing the log** + +Click the clear-messages button (trash icon) to empty the log entirely. This just clears the on-screen view — it doesn't disconnect you. + +**Max Log Messages** + +The log caps how many messages it displays — by default the most recent **1000**. This keeps high-volume streams from slowing things down. If you need to keep more on screen, increase **Max Log Messages** in the app settings. + +Steps to find a specific message in a busy log: +1. Type part of the message into the **Filter messages…** box. +2. Review the filtered results (oldest at top, newest at bottom). +3. Click an entry to copy its full payload. +4. Click the clear (✕) on the filter to return to the full log. + + + +--- + +## History & persistence + +API Dash remembers your WebSocket work in two ways. + +**Saved requests** + +When you save a WebSocket request, it keeps: +- the **URL**, +- the **Headers** and **Params** you set up, +- and your **Settings** (the heartbeat and auto-reconnect options). + +So you can reopen a saved WebSocket request later and connect again without reconfiguring it. + +**The History tab** + +The **History** tab lets you reopen a past WebSocket session and review its message log in **read-only** form. This is useful for going back over what was sent and received during an earlier session without starting a new connection. + +> Tip: Save the requests you connect to often. Combined with environment variables in the URL (`{{WS_URL}}`), you can switch between servers in one click. + + + +--- + +## Troubleshooting & tips + +- **Use `wss://` for secure endpoints.** For anything over the public internet — especially with tokens or passwords — prefer the encrypted `wss://` form over plain `ws://`. +- **Connection keeps dropping while idle?** A proxy or load balancer may be closing connections that look inactive. Turn on **WebSocket Heartbeat** in the Settings tab to send keep-alive pings. +- **Server needs auth after connecting?** Some servers ignore handshake headers and expect credentials in your first message instead. Send an auth/login message right after connecting — saving it as a **Template** makes this one click. +- **On a flaky network?** Turn on **Auto Reconnect** so API Dash retries automatically when the connection drops. +- **Changed the Ping Interval but nothing happened?** Interval changes apply on the **next** connect. Disconnect and reconnect to apply them. +- **High-volume stream getting cut off?** The log shows the most recent 1000 messages by default. Increase **Max Log Messages** in app settings to keep more on screen. +- **Send button greyed out?** You're not connected yet. Click **Connect** first — Send only works on a live connection. +- **Can't connect at all?** Double-check the URL (right prefix, correct host/port), confirm the server is running, and check whether your network or firewall blocks WebSocket traffic. Failed handshakes are logged with details to help you pinpoint the issue. +- **Headers not authenticating you?** Confirm whether the server expects credentials at handshake time (Headers tab) or after connecting (first message/Template). + +--- + +## FAQ + +- **Can I send binary data (files, images) over the connection?** + - No. Messages are sent as text frames. You can send plain text or JSON; binary frames aren't sent from the UI. +- **Do keep-alive pings show up in my message log?** + - No. Heartbeat pings happen quietly at the protocol level and are kept out of the log. +- **Will my saved request remember the heartbeat and reconnect settings?** + - Yes. Saved WebSocket requests keep their URL, Headers, Params, and Settings. +- **Can I use environment variables in the WebSocket URL?** + - Yes. Use a variable like `{{WS_URL}}` and API Dash substitutes its value before connecting. +- **How do I resend a message I sent earlier?** + - Use the **Recently Sent** strip (click an item to refill the input) or save the message as a **Template**. + +You're set! Switch a request to WebSocket, enter your `ws://` or `wss://` URL, click Connect, and start sending and receiving messages in real time.