Choose the transport that the feature needs

How to do it

Polling is a plain GET, so caching, rate limits and logs work as for any request. Server-sent events are one long HTTP answer that the browser reconnects and resumes on its own. Their format is in stream in a standard format. A WebSocket is a separate protocol with its own framing, so every limit and check must be built again. Choose it for chat, shared editing or games, where the client sends many small messages. Write the choice and its reason in the contract for each live feature.

Examples

JavaScript example

const events = new EventSource('/v1/orders/events');
events.addEventListener('order.shipped', event => {
  const order = JSON.parse(event.data);
  showShipped(order.orderId);
});

Python example

import json
from starlette.responses import StreamingResponse

async def order_events(request):
    async def stream():
        async for event in subscribe(request.user.shop_id):
            yield f"id: {event.id}\nevent: {event.type}\ndata: {json.dumps(event.data)}\n\n"
    return StreamingResponse(stream(), media_type="text/event-stream")

How to check

Each live endpoint in the contract names its transport and the reason. Each WebSocket endpoint lists at least one message type the client sends after it connects.

Sources

• WHATWG HTML server-sent events
• RFC 6455 The WebSocket Protocol

Related rules

• Stream in a standard format and describe each item in API design