How to Spike a Third-Party Realtime API Before You Commit to Build

When a feature depends on a third-party realtime API, the estimate is only as good as your assumptions about that API's behavior. Latency, message ordering, clock ownership, and reconnection semantics are unknowable until you have hit the real endpoint with real traffic patterns. A short technical spike — two to five focused days of investigation — answers those questions with evidence, so the build estimate rests on measured behavior rather than vendor documentation and guesswork.

By the end of this guide, you will have: a reproducible spike plan that produces a written reliability assessment for any third-party realtime API, including measured latency figures, connection behavior under failure, message-ordering and clock-semantics findings, and a clear go/no-go recommendation for the build phase.

The spike produces four deliverables:

1. Latency profile — round-trip, first-message, and sustained-throughput figures under realistic network conditions.
2. Clock-ownership analysis — whether timestamps are server-authoritative or client-generated, and what that means for your data model.
3. Reconnection behavior — what happens when connections drop, and whether client-side recovery logic is required.
4. Recommendation — a written go/no-go assessment with evidence for each claim.

Before starting the spike, confirm the following are available.

The spike follows a deliberate sequence. Each step answers a specific question. Do not skip ahead — the later steps depend on the measurements and tooling established earlier.

Step 1 — Build a minimal connectivity harness

1. 1

   Build Harness

   Create a small client that connects to the realtime API, authenticates, subscribes to a test channel or topic, and logs every message with a client-side timestamp.

2. 2

   Measure Latency

   Run the connectivity harness from the network location your production workload will actually use. If your production servers are in us-east-1, run the spike from us-east-1. If your users are geographic, run it from the regions that matter.

3. 3

   Stress Test

   Production realtime features do not receive one message per minute. They receive bursts. The spike must measure latency under the message rate your production feature will actually handle.

4. 4

   Check Clocks

   Realtime APIs timestamp their messages. The critical question is: whose clock produced that timestamp?

5. 5

   Test Recovery

   Production connections drop. The spike must establish what happens when they do.

6. 6

   Write Report

   The spike is worthless if its findings stay in a log file. Write a report that answers the five questions the build team actually needs answered:

The harness should be deliberately minimal. The point is to measure the API's behavior, not to build part of the production feature.

// spike-client.js — simplified
const WebSocket = require('ws');

const ws = new WebSocket('<API_WS_URL>', {
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` }
});

const connectTime = Date.now();

ws.on('open', () => {
  console.log('CONNECTED', Date.now() - connectTime);
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'spike-test'
  }));
});

ws.on('message', (data) => {
  const payload = JSON.parse(data.toString());
  console.log(JSON.stringify({
    receivedAt: Date.now(),
    sentAt: payload.sentAt || null,
    serverTime: payload.serverTime || null,
    payload
  }));
});

ws.on('close', (code, reason) => {
  console.log('CLOSED', code, reason.toString());
});

ws.on('error', (err) => {
  console.error('ERROR', err.message);
});

Run the harness for a fixed interval — five minutes is a reasonable starting point — and save the output to a log file.

API_TOKEN="<API_TOKEN>" node spike-client.js > spike-1.log

Expected result: The connection succeeds, authenticated subscription messages arrive, and the log file contains one line per received message with a client-side timestamp.

Step 2 — Measure connection latency across regions

For each region, measure:

• Time to connect — from client initiation to the server's connection confirmation.
• Time to first message — from the moment the client publishes a test message to the moment it receives its own message back on the subscribed channel.
• Round-trip latency — publish a message with a client timestamp, receive it back, and compute receivedAt - sentAt.

Repeat the measurement at least 10 times per region. Realtime APIs are noisy; a single sample is not evidence.

for i in $(seq 1 10); do
  API_TOKEN="<API_TOKEN>" node spike-client.js >> spike-2-region.log
  sleep 5
done

Expected result: A table of measurements per region showing minimum, median, p95, and maximum for connection time and round-trip latency.

Step 3 — Measure sustained latency under a realistic message rate

Estimate the production message rate first. A typical financial-feed integration might receive 10–50 messages per second during active trading. A chat feature might receive 1–5 per second. Use the rate that reflects reality, not the rate the vendor advertises.

Extend the harness to publish test messages at your target rate and measure per-message latency:

// burst-publish.js — simplified
const WebSocket = require('ws');
const ws = new WebSocket('<API_WS_URL>', {
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` }
});

const RATE_PER_SECOND = 20;
const DURATION_SECONDS = 60;

let sentCount = 0;
let receivedCount = 0;

function sendBatch() {
  const now = Date.now();
  for (let i = 0; i < RATE_PER_SECOND; i++) {
    ws.send(JSON.stringify({
      type: 'publish',
      channel: 'spike-test',
      data: { sentAt: now, seq: sentCount++ }
    }));
  }
}

ws.on('open', () => {
  const interval = setInterval(sendBatch, 1000);
  setTimeout(() => {
    clearInterval(interval);
    setTimeout(() => {
      console.log('SUMMARY', { sentCount, receivedCount });
      ws.close();
    }, 5000);
  }, DURATION_SECONDS * 1000);
});

ws.on('message', (data) => {
  receivedCount++;
  const payload = JSON.parse(data.toString());
  if (payload.sentAt) {
    console.log('LATENCY', Date.now() - payload.sentAt);
  }
});

Run this once. Then run it again with the burst pattern your production workload will have — for example, 100 messages in one second followed by 30 seconds of silence, repeated.

Expected result: A latency distribution under sustained and bursty load. Confirm whether latency degrades as the message rate increases, and whether the API drops or reorders messages under load.

Step 4 — Determine clock ownership

Check every field that appears to be a timestamp and determine whether it was set by the server or by the publishing client.

1. Publish a message with a deliberately incorrect client timestamp — for example, set sentAt to 24 hours in the past.
2. Observe how the server echoes or transforms that field.
3. Compare the server-provided timestamps against your own clock to detect skew.

ws.send(JSON.stringify({
  type: 'publish',
  channel: 'spike-test',
  data: {
    sentAt: Date.now() - 86400000,  // 24 hours in the past
    intentionallyWrong: true
  }
}));

The pattern you observe tells you which clock to trust:

• If the server overwrites the timestamp, the server is authoritative. Fine for ordering, but confirm the server clock has reasonable skew against real time.
• If the server preserves the client timestamp, your message ordering is only as good as the clients' clocks. This has direct consequences for any "latest state wins" logic in your data model.
• If the server provides a separate serverTime field alongside the client timestamp, compare them. The delta between them is your clock-skew measurement.

Expected result: A clear statement of which component owns the timestamp, and a measured clock-skew figure between the server and your client.

Step 5 — Test reconnection behavior

Test the following scenarios, in order:

1. Graceful server shutdown — if your sandbox allows it, restart the API service and observe the close code and whether the client is expected to reconnect manually.
2. Network interruption — disconnect the client's network for 10 seconds, then restore it. Observe whether the client library auto-reconnects, whether messages received during the outage are replayed or permanently lost, and whether any messages are duplicated on reconnect.
3. Idle timeout — leave the connection open with no traffic for the vendor's documented idle timeout, and observe whether the server closes the connection and what close code it sends.

// Reconnection observation — simplified
let messagesBySeq = {};
let duplicateCount = 0;

ws.on('message', (data) => {
  const payload = JSON.parse(data.toString());
  if (payload.seq !== undefined) {
    if (messagesBySeq[payload.seq]) {
      duplicateCount++;
      console.log('DUPLICATE', payload.seq);
    }
    messagesBySeq[payload.seq] = true;
  }
  console.log('STATE', {
    readyState: ws.readyState,
    duplicatesSeen: duplicateCount,
    lastSeq: payload.seq
  });
});

For each scenario, record:

• The close code and reason.
• Whether client-side reconnection logic triggered automatically.
• Whether messages were lost, replayed, or duplicated after reconnect.
• How long the gap in message delivery lasted.

Expected result: A documented reconnection matrix showing behavior for each failure scenario and the delivery semantics (at-most-once, at-least-once, or exactly-once).

Step 6 — Write the spike report

1. Latency — what is the realistic p95 latency from your production network location, and does it hold under your production message rate?
2. Clock semantics — who owns the timestamp, and what does your data model need to do to handle it?
3. Reconnection — who is responsible for recovering from dropped connections, and what delivery semantics does the API actually provide?
4. Cost envelope — did the spike reveal any rate-limit or quota behavior that will constrain the production design?
5. Go/no-go — based on the evidence, should the feature be built against this API, built against a different provider, or built with a fallback path?

Several settings materially affect spike results. The right value depends on your workload, not on a universal default.

Estimate from actual business requirements. A chat feature handling 200 concurrent users typically generates 1–5 messages per second. A market-data feed generates 20–100 messages per second during active periods. Use the figure your feature will reasonably encounter.

The spike is complete when its findings are reproducible and its conclusions are traceable to specific log entries.

Before the build phase begins, confirm the following based on spike findings: