TickDB REST vs WebSocket: A Practical Guide to Choosing the Right API Protocol

The decision between REST and WebSocket is not a philosophical debate — it is a matter of engineering trade-offs that directly affect latency, server load, and the complexity of your client code. Choosing the wrong protocol for a given use case transforms a straightforward integration into a maintenance burden. Choosing correctly lets you build systems that scale without surprises.

For most developers working with market data APIs, the heuristic is straightforward: pull historical data over REST, subscribe to real-time streams over WebSocket. This article dissects why that division of labor exists, what happens when you ignore it, and how to implement both protocols correctly in production. The goal is not to advocate for one approach over the other — it is to give you a framework for matching protocol to problem.

---

The Fundamental Asymmetry of Market Data

Market data has two distinct consumption patterns that map cleanly onto two distinct transport mechanisms.

The first pattern is request-response: a client asks for a specific dataset, the server fulfills it, and the interaction ends. Historical OHLCV candles, symbol metadata, and exchange status queries all follow this pattern. The data is static by the time the server returns it. There is no benefit to maintaining a persistent connection because nothing is changing after the response arrives.

The second pattern is continuous streaming: market state evolves in real time, and the client needs to receive every update as it happens. Order book changes, trade executions, and price ticks are inherently ephemeral. Waiting for a client to poll every second means missing the microstructure event that matters.

REST and WebSocket map directly onto these two patterns. REST excels at stateless, one-shot data retrieval. WebSocket excels at low-latency, bidirectional, long-lived connections. Forcing either pattern into the other's protocol is technically possible but practically costly.

---

REST in Practice: Historical Data Retrieval

REST is a request-response protocol built on top of HTTP. The client sends a request; the server sends a response; the connection closes. Each request is self-contained — it carries all the information the server needs to fulfill it, including authentication headers, query parameters, and pagination tokens.

For historical market data, this model is ideal. The data exists on disk or in a database. The server retrieves it, serializes it, and sends it back. The client does not need to maintain any state between requests. If the client crashes and restarts, it simply re-requests the data it needs. There is no connection to re-establish, no stream to re-synchronize.

The Correct REST Pattern

A well-designed REST integration for TickDB follows a predictable pattern. Authentication uses a header — never a URL parameter — to keep credentials out of server logs. Every request carries a timeout. Rate limit responses are handled explicitly.

import os
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

# Load API key from environment — never hardcode credentials
TICKDB_API_KEY = os.environ.get("TICKDB_API_KEY")
if not TICKDB_API_KEY:
    raise ValueError("Set TICKDB_API_KEY environment variable before running")

BASE_URL = "https://api.tickdb.ai/v1"

# Configure retries with exponential backoff for transient failures
session = requests.Session()
retry_strategy = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
session.mount("https://", adapter)

headers = {
    "X-API-Key": TICKDB_API_KEY,
    "Accept": "application/json"
}

def fetch_kline_data(symbol: str, interval: str, limit: int = 100) -> dict:
    """
    Fetch historical OHLCV kline data via REST.
    
    Args:
        symbol: Exchange-specific symbol (e.g., "AAPL.US", "BTC.Binance")
        interval: Candle interval (e.g., "1m", "1h", "1d")
        limit: Number of candles to retrieve (max varies by interval)
    
    Returns:
        dict: API response containing kline data array
    """
    url = f"{BASE_URL}/market/kline"
    params = {
        "symbol": symbol,
        "interval": interval,
        "limit": limit
    }
    
    response = session.get(
        url,
        headers=headers,
        params=params,
        timeout=(3.05, 10)  # Connect timeout, read timeout
    )
    
    # Handle rate limiting explicitly
    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return fetch_kline_data(symbol, interval, limit)
    
    response.raise_for_status()
    return response.json()

# Example usage
data = fetch_kline_data(symbol="AAPL.US", interval="1h", limit=500)
print(f"Retrieved {len(data.get('data', []))} candles")

This pattern works well for backtesting, strategy research, and historical analysis. The client controls the request cadence. The server remains stateless. There are no long-lived connections to manage, no heartbeat mechanisms to implement, no reconnection logic to debug.

What Happens When You Use REST for Real-Time Data

The temptation to use REST for real-time data usually stems from familiarity. REST is well-understood. Tooling is ubiquitous. Debugging is straightforward. However, the approach breaks down under load.

To receive real-time updates via REST, a client must poll — repeatedly sending requests to check for new data. At one request per second, you introduce a minimum 1-second latency between when an event occurs and when your system learns about it. At 10 requests per second, you increase server load tenfold and still miss events that occur between your polls.

More critically, polling creates a detection problem: how do you know you missed an update? With a WebSocket stream, you receive every tick in sequence. With polling, a tick that occurs between your requests is simply gone.

Polling is acceptable for low-frequency data, dashboard refreshes, or systems where eventual consistency is sufficient. It is not acceptable for latency-sensitive trading strategies.

---

WebSocket in Practice: Real-Time Streaming

WebSocket is a persistent, bidirectional communication protocol. After an initial HTTP handshake, the connection upgrades to a long-lived TCP socket. Both client and server can send messages at any time without the overhead of re-establishing a connection for each message.

For real-time market data, this matters enormously. A price tick that occurs at 09:30:00.123 can reach your client by 09:30:00.145 — a difference of 22 milliseconds, not 1 to 5 seconds. The order book snapshot you receive reflects the current state, not a snapshot from some indeterminate moment in the past.

The Correct WebSocket Pattern

A production-grade WebSocket integration requires several components that a simple example often omits. Heartbeat messages keep the connection alive through NAT timeouts and proxy idle limits. Reconnection logic handles the inevitable disconnection events without crashing your application. Backoff with jitter prevents thundering-herd reconnection storms when many clients reconnect simultaneously after a server restart.

import os
import json
import time
import random
import threading
import logging
from typing import Callable, Optional

try:
    import websocket
except ImportError:
    raise ImportError("Install websocket-client: pip install websocket-client")

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Load API key from environment
TICKDB_API_KEY = os.environ.get("TICKDB_API_KEY")
if not TICKDB_API_KEY:
    raise ValueError("Set TICKDB_API_KEY environment variable before running")

class TickDBWebSocketClient:
    """
    Production-grade WebSocket client for TickDB real-time data.
    
    Handles heartbeat, automatic reconnection with exponential backoff and jitter,
    rate limit responses, and thread-safe message dispatching.
    """
    
    def __init__(
        self,
        api_key: str,
        on_message: Optional[Callable[[dict], None]] = None,
        on_error: Optional[Callable[[Exception], None]] = None
    ):
        self.api_key = api_key
        self.on_message = on_message
        self.on_error = on_error
        self.ws: Optional[websocket.WebSocketApp] = None
        self.running = False
        self.reconnect_thread: Optional[threading.Thread] = None
        self.lock = threading.Lock()
        
        # Reconnection parameters
        self.base_delay = 1.0          # Initial delay in seconds
        self.max_delay = 60.0          # Maximum delay cap
        self.max_retries = float('inf') # Unlimited retries
        
        # Heartbeat parameters
        self.heartbeat_interval = 25.0  # Send ping every 25 seconds
        self.last_pong_time = time.time()
        
    def _get_ws_url(self) -> str:
        """
        Construct WebSocket URL with API key as query parameter.
        
        Note: WebSocket uses URL parameters for auth, not headers.
        REST uses X-API-Key header. This is a protocol difference.
        """
        return f"wss://stream.tickdb.ai/ws?api_key={self.api_key}"
    
    def connect(self):
        """Establish WebSocket connection and start background threads."""
        with self.lock:
            if self.running:
                logger.warning("Client already running")
                return
                
            self.running = True
            self.ws = websocket.WebSocketApp(
                self._get_ws_url(),
                on_message=self._on_message,
                on_error=self._on_error or self._default_error_handler,
                on_close=self._on_close,
                on_open=self._on_open
            )
            
            # Run WebSocket in a daemon thread
            ws_thread = threading.Thread(
                target=self.ws.run_forever,
                kwargs={"ping_interval": self.heartbeat_interval},
                daemon=True
            )
            ws_thread.start()
            logger.info("WebSocket connection initiated")
    
    def _on_open(self, ws):
        """Called when WebSocket connection is established."""
        logger.info("WebSocket connection opened — subscribing to depth channel")
        self._subscribe_depth(["AAPL.US", "NVDA.US"])
    
    def _subscribe_depth(self, symbols: list[str]):
        """Subscribe to order book depth updates for given symbols."""
        message = {
            "cmd": "sub",
            "params": {
                "channels": ["depth"],
                "symbols": symbols
            }
        }
        self.ws.send(json.dumps(message))
        logger.info(f"Subscribed to depth for: {symbols}")
    
    def _on_message(self, ws, message: str):
        """Handle incoming WebSocket message."""
        try:
            data = json.loads(message)
            
            # Handle pong responses (server heartbeat reply)
            if data.get("cmd") == "pong":
                self.last_pong_time = time.time()
                return
            
            # Handle rate limit responses
            if data.get("code") == 3001:
                retry_after = data.get("retry_after", 5)
                logger.warning(f"Rate limited — waiting {retry_after} seconds")
                time.sleep(retry_after)
                return
            
            # Dispatch to callback
            if self.on_message:
                self.on_message(data)
                
        except json.JSONDecodeError as e:
            logger.error(f"Failed to parse message: {e}")
    
    def _default_error_handler(self, ws, error):
        """Default error handler logs the error."""
        logger.error(f"WebSocket error: {error}")
    
    def _on_close(self, ws, close_status_code, close_msg):
        """Called when WebSocket connection closes."""
        logger.warning(f"WebSocket closed: {close_status_code} — {close_msg}")
        if self.running:
            self._schedule_reconnect()
    
    def _schedule_reconnect(self):
        """Schedule a reconnection attempt with exponential backoff and jitter."""
        if not self.running:
            return
            
        # Calculate delay with exponential backoff
        delay = min(self.base_delay * (2 ** self._retry_count), self.max_delay)
        # Add jitter: random value up to 10% of delay
        jitter = random.uniform(0, delay * 0.1)
        total_delay = delay + jitter
        
        logger.info(f"Scheduling reconnect in {total_delay:.2f} seconds (retry {self._retry_count})")
        
        def delayed_reconnect():
            time.sleep(total_delay)
            self._retry_count += 1
            self.connect()
        
        self.reconnect_thread = threading.Thread(target=delayed_reconnect, daemon=True)
        self.reconnect_thread.start()
    
    def disconnect(self):
        """Gracefully close the WebSocket connection."""
        with self.lock:
            self.running = False
            if self.ws:
                self.ws.close()
            logger.info("WebSocket client stopped")
    
    def run_forever(self):
        """Block the current thread, keeping the connection alive."""
        self.connect()
        try:
            while self.running:
                time.sleep(1)
        except KeyboardInterrupt:
            self.disconnect()


# Example: Process incoming depth updates
def handle_depth_update(data: dict):
    """Example callback for depth channel updates."""
    if data.get("channel") != "depth":
        return
    
    symbol = data.get("symbol")
    bids = data.get("bids", [])  # List of [price, size] pairs
    asks = data.get("asks", [])
    
    # Calculate order book pressure
    bid_volume = sum(size for _, size in bids[:5])
    ask_volume = sum(size for _, size in asks[:5])
    
    if bid_volume + ask_volume > 0:
        pressure_ratio = bid_volume / (bid_volume + ask_volume)
        print(f"{symbol} | Bid pressure (top 5): {pressure_ratio:.2%} | "
              f"Bid vol: {bid_volume:,.0f} | Ask vol: {ask_volume:,.0f}")


if __name__ == "__main__":
    client = TickDBWebSocketClient(
        api_key=TICKDB_API_KEY,
        on_message=handle_depth_update
    )
    client.run_forever()

What Happens When You Use WebSocket for Historical Data

WebSocket for historical data retrieval is not impossible — but it is architecturally wrong for most use cases.

To fetch historical klines over WebSocket, you would need to maintain a persistent connection, send a request message, wait for a potentially large response stream, and then either keep the connection open for future use or close it. This adds connection management overhead for a one-time data transfer. The server must maintain state for your session. Your client must implement all the reconnection logic even though the historical data will not change.

The inefficiency is not theoretical. A WebSocket connection consumes server-side file descriptors and memory. A REST request consumes a fraction of those resources for a fraction of the time. At scale — hundreds or thousands of concurrent clients — the difference in server infrastructure costs becomes material.

---

Scenario Comparison: When to Use Each Protocol

The table below summarizes the decision criteria. These are not hard rules carved in stone — they are guidelines based on the fundamental characteristics of each protocol.

Criterion	REST	WebSocket
Data nature	Static, complete at response time	Dynamic, evolves continuously
Update frequency	One-time or infrequent	High-frequency, continuous
Latency requirement	Seconds acceptable	Sub-second required
Client control	Client initiates every request	Server pushes without polling
Connection lifecycle	Short-lived per request	Long-lived, persistent
Server resource usage	Stateless, low per-request	Stateful, higher per-connection
Resume after failure	Re-request the data	Reconnect and re-subscribe
Best for	Historical OHLCV, symbol lists, exchange status	Live prices, order book, trade ticks

Mixed Architectures

Production systems typically use both protocols in a complementary architecture. A trading strategy might:

1. Use REST during initialization to fetch the historical kline baseline for a symbol (e.g., the past 500 one-hour candles for backtesting).
2. Establish a WebSocket connection to receive live order book updates and trade ticks as the market session progresses.
3. Use REST again after market close to retrieve the completed session's final candles for record-keeping.

This separation respects the fundamental strengths of each protocol. REST handles bulk data transfer with low overhead and no connection management complexity. WebSocket handles real-time updates with minimal latency and no polling inefficiency.

---

Common Mistakes and How to Avoid Them

Mistake 1: Polling REST for Real-Time Data

This is the most common integration error. Developers familiar with REST apply it everywhere because it is comfortable. The result is a system with 1-to-5-second data lag, unnecessary server load, and missed market events.

Fix: Use the WebSocket depth and trades channels for anything that changes more frequently than once per minute.

Mistake 2: WebSocket Authentication via Header

Some developers assume WebSocket authentication works identically to REST — passing credentials in a header. WebSocket does not support custom headers after the upgrade handshake. API keys must be passed as URL query parameters.

Fix: Append ?api_key=YOUR_KEY to the WebSocket URL. Keep the key out of application logs that might be accessible to third parties.

Mistake 3: No Reconnection Logic

WebSocket connections drop. It is not a question of if — it is a question of when and why. NAT timeouts, server maintenance, network partitions, and mobile device connectivity changes all terminate connections silently.

Fix: Implement automatic reconnection with exponential backoff and jitter. Log reconnection events to detect patterns that might indicate a deeper problem.

Mistake 4: Ignoring Rate Limits on WebSocket

While less common than REST rate limiting, WebSocket endpoints also enforce rate limits. Failing to handle a 3001 response with the appropriate backoff can result in temporary or permanent connection drops.

Fix: Treat 3001 responses as a signal to pause subscriptions briefly and resume with a reduced message frequency.

Mistake 5: Single-Threaded WebSocket in a Trading Engine

A blocking WebSocket receive loop in the main thread of a trading engine creates a bottleneck. Market data arrives asynchronously; your order management and risk checks operate on their own cadence.

Fix: Decouple WebSocket message reception from processing. Use a queue or event-driven architecture so that a slow message handler does not block the receipt of subsequent updates.

---

Architecture Diagram: Mixed REST/WebSocket System

┌─────────────────────────────────────────────────────────────┐
│                    Trading Application                       │
│                                                              │
│  ┌──────────────┐        ┌──────────────────────────────┐    │
│  │   REST API   │◄───────│  Historical Data Retrieval   │    │
│  │  /kline      │        │  • 500 1h candles on startup │    │
│  │  /symbols    │        │  • Symbol metadata queries    │    │
│  └──────────────┘        │  • Exchange status checks     │    │
│                          └──────────────────────────────┘    │
│                                                              │
│  ┌──────────────────┐    ┌──────────────────────────────┐    │
│  │  WebSocket Stream │◄───│  Real-Time Market Data       │    │
│  │  depth + trades   │    │  • Order book L1-L10 updates  │    │
│  │  ping/pong        │    │  • Trade tick ingestion      │    │
│  └──────────────────┘    │  • Pressure ratio calculation │    │
│         │                └──────────────────────────────┘    │
│         ▼                                                    │
│  ┌──────────────────────────────────────────────────────┐    │
│  │              Message Processing Queue                  │    │
│  │   (Decoupled from WebSocket receive loop)             │    │
│  └──────────────────────────────────────────────────────┘    │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────────────────────────────────────────────┐    │
│  │            Strategy Engine / Order Manager            │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

---

Implementation Checklist

Before deploying an integration that uses either protocol, verify the following:

REST checklist:

• API key loaded from environment variable, not hardcoded
• Timeout configured on all requests (connect and read)
• Retry logic with exponential backoff for transient errors
• Explicit handling of HTTP 429 with Retry-After header parsing
• Pagination handled correctly for large result sets

WebSocket checklist:

• API key passed as URL query parameter, not header
• Heartbeat (ping/pong) configured to prevent NAT timeouts
• Automatic reconnection with exponential backoff and jitter
• Rate limit responses (code: 3001) handled with backoff
• Message processing decoupled from the receive loop
• Graceful shutdown disconnects cleanly without orphaning threads

---

Conclusion

The REST versus WebSocket decision is not about preference — it is about matching the transport mechanism to the data's characteristics. Static, one-shot data retrieval belongs on REST. Continuous, low-latency streaming belongs on WebSocket. Mixing them in the wrong direction introduces latency, server load, and architectural complexity without benefit.

TickDB's API surface reflects this design philosophy directly. The /kline and /symbols REST endpoints serve bulk data retrieval. The WebSocket depth and trades channels serve real-time streaming. Understanding which endpoint serves which purpose — and implementing each with production-grade resilience — is the foundation for a reliable market data integration.

The heuristic is simple: when in doubt, ask whether the data exists completely at the moment of your request. If yes, use REST. If the data is still being generated as you read this, use WebSocket.

---

Next Steps

If you are building a backtesting pipeline, use the TickDB /v1/market/kline REST endpoint with the code pattern shown above. Start with 1-hour candles for a broad market view, then drill into 1-minute candles for microstructure analysis.

If you are building a live trading system, establish a WebSocket connection using the TickDBWebSocketClient pattern. Subscribe to the depth channel for order book pressure signals and the trades channel for execution flow analysis.

If you need both in a single workflow, start with REST for historical context, establish WebSocket for real-time updates, and close with REST for post-session record retrieval. The combination is not a compromise — it is the correct architecture.

If you use AI coding assistants, search for the tickdb-market-data SKILL in your tool's marketplace for an integrated development experience that includes pre-built connection templates, authentication handling, and example strategy code.

---

This article does not constitute investment advice. Markets involve risk; past performance does not guarantee future results. API integrations should be tested in a paper trading environment before live deployment.