Real-time and event-driven APIs: WebSockets, SSE, pub/sub, and AsyncAPI

Classic REST APIs work on a simple pattern: the client asks, the server answers. For data that can originate server-side at any time (a new message, a sensor reading, a price change), that's inefficient, because the client would have to keep asking (polling). Four building blocks solve this in different ways.

WebSockets, according to MDN, open a two-way, interactive communication session between browser and server. You can send messages and receive responses without having to poll the server. The connection starts as HTTP and is upgraded via a handshake; headers such as Sec-WebSocket-Key, Sec-WebSocket-Accept, Sec-WebSocket-Version, and Sec-WebSocket-Protocol are involved. The protocol is specified in RFC 6455. Suited to chats, collaborative work, and games, in short anything where both sides can send at any time.

Server-Sent Events (SSE) are, according to MDN, a one-way connection: the client cannot use it to send events to the server. In the browser, the EventSource interface handles this; the server responds with the MIME type text/event-stream. If the connection drops, it is automatically re-established by default. SSE is leaner than WebSockets and ideal when only the server needs to push (live tickers, notifications, progress indicators).

Event-driven, or message-based, architecture decouples sender and receiver via publish/subscribe and a message broker. Producers publish messages to topics/channels, consumers subscribe to them without knowing each other directly. Typical protocols and systems:

• MQTT: a lightweight pub/sub protocol, common in IoT environments.
• AMQP: a message-oriented protocol for reliable queuing.
• Apache Kafka: a distributed platform for high throughput and durable event logs.

Webhooks reverse the call direction: instead of the client asking, the server calls a URL registered by the client via HTTP when an event occurs (an HTTP callback). This suits rare, event-based notifications between systems, for example payment confirmations or Git pushes.

AsyncAPI is the specification used to describe such interfaces. MDN's own documentation names it explicitly as a tool for WebSocket-based APIs and contrasts it with OpenAPI: just as OpenAPI describes REST APIs, AsyncAPI describes event-driven architectures built on protocols such as WebSocket. The official documentation summarizes the core concepts (server, producer, consumer, channel, application, protocol, message) as the building blocks of this description.

How to choose:

• Both sides send in real time: WebSockets.
• Only the server pushes to the browser: SSE (simpler, with auto-reconnect).
• Decoupling systems, many recipients, IoT: pub/sub with a broker (MQTT, AMQP, Kafka).
• Occasional server-to-server notification: webhooks.
• Documenting such async interfaces: AsyncAPI.

// Server-Sent Events in the browser (MDN: EventSource)
const evtSource = new EventSource("sse-demo.php");

evtSource.onmessage = (event) => {
  console.log("New server message:", event.data);
};

evtSource.onerror = (err) => {
  console.error("EventSource failed:", err);
};

// Server-side (PHP): response as text/event-stream
// header("Content-Type: text/event-stream");
// header("Cache-Control: no-cache");
// echo "data: pong\n\n";

A one-way SSE connection: the client only receives, the server pushes with MIME type text/event-stream.

Sources

• WebSocket API (WebSockets) MDN Web Docs
• Using server-sent events MDN Web Docs
• Concepts Overview - AsyncAPI AsyncAPI Initiative