A connection URL is only the beginning

A WebSocket connection may carry subscriptions, confirmations, notifications and keepalive messages through the same URL. Documenting only the handshake misses the information you need to understand the protocol.

apispy treats these exchanges as streams. It groups observations into channels and describes the message types seen in each direction. Server-sent events are the receive-only case: the server emits messages over an HTTP connection that remains open.

How to document a stream

  1. Open the site in the analysis browser. Navigate to a feature that uses live updates, notifications or streamed responses.
  2. Exercise the live interaction. Let the connection receive messages and perform actions that trigger outgoing messages.
  3. Choose the stream host. Open the Streams view to review its channels, message directions and observed payload structures.
  4. Export AsyncAPI. Use the available stream export to save the generated document and inspect it with tools that support AsyncAPI 3.

Separate messages by what they mean

For structured JSON traffic, apispy looks for a payload field that distinguishes message types, including candidates such as type, event, op, action and method. The selected discriminator is recorded as x-apispy-type-key.

Illustrative stream observations
out  { "type": "subscribe", "topic": "updates" }
in   { "type": "welcome" }
in   { "type": "notification", "count": 3 }
in   { "type": "keepalive" }

For server-sent events, explicit event: names identify message types when present. Otherwise apispy uses the payload to discriminate between messages. This also supports JSON events from streaming APIs.

Keep the limits visible

Non-JSON text, such as an IRC message, is represented by a truncated sample rather than a fabricated object schema. Binary frames are counted, not decoded. A capture also cannot describe messages that never occurred while you were browsing.

Exercise subscription changes, incoming updates and disconnect or error scenarios where appropriate. The result remains a record of observed traffic rather than a complete definition of the server’s event protocol.

Choose AsyncAPI for events, OpenAPI for requests

AsyncAPI 3 defines a format for describing message-driven APIs. It complements the OpenAPI document for ordinary HTTP requests and responses; it does not replace it.

Both outputs come from the same local workspace. Before you share exported documents, review retained example values and read how apispy handles captured data.

Product behavior described here reflects apispy v0.1. Inferred documentation depends on the traffic you observe.