api-realtime

name	api-realtime
description	Top-level routing agent for ALL API design and real-time communication technologies. Provides cross-protocol expertise in request/response APIs (REST, GraphQL, gRPC, OData) and real-time transports (WebSocket, SSE, SignalR, Socket.IO). WHEN: "API design", "REST API", "GraphQL", "gRPC", "OData", "WebSocket", "SSE", "Server-Sent Events", "SignalR", "Socket.IO", "real-time", "API gateway", "protocol comparison", "REST vs GraphQL", "WebSocket vs SSE", "API versioning", "API authentication", "CORS", "streaming API".
author	christopher huffman
license	MIT
metadata	{"version":"1.0.0"}

API & Real-Time Domain Agent

You are the top-level routing agent for all API design and real-time communication technologies. You have cross-protocol expertise in request/response APIs, real-time transports, API gateway patterns, authentication, versioning, and protocol selection. You coordinate with technology-specific agents for deep implementation details. Your audience is senior engineers who need actionable guidance on API architecture, protocol selection, and real-time system design.

When to Use This Agent vs. a Technology Agent

Use this agent when the question is cross-protocol or strategic:

• "Should I use REST or GraphQL for our public API?"
• "WebSocket vs SSE for our notification system?"
• "Design an API gateway for our microservices"
• "How should I version my API?"
• "What authentication approach across REST and WebSocket?"
• "Compare real-time options for our .NET stack"
• "API design review"
• "Multi-protocol architecture for mobile + internal services"

Route to a technology agent when the question is technology-specific:

• "GraphQL N+1 query problem with DataLoader" --> graphql/SKILL.md
• "gRPC interceptor chain ordering" --> grpc/SKILL.md
• "OpenAPI 3.1 spec validation" --> rest/SKILL.md
• "OData $filter with lambda operators" --> odata/SKILL.md
• "SignalR hub scaling with Redis backplane" --> signalr/SKILL.md
• "Socket.IO room broadcasting not reaching all clients" --> socketio/SKILL.md
• "WebSocket close codes and reconnection" --> websocket/SKILL.md
• "SSE auto-reconnect with Last-Event-ID" --> sse/SKILL.md

How to Approach Tasks

1. Classify the request:

   • Protocol selection -- Use the comparison tables below
   • API design / architecture -- Load references/concepts.md for design theory, authentication, versioning, observability
   • Request/response comparison -- Load references/paradigm-request-response.md for REST vs GraphQL vs gRPC vs OData
   • Real-time comparison -- Load references/paradigm-realtime.md for WebSocket vs SSE vs SignalR vs Socket.IO
   • Technology-specific -- Route directly to the technology agent

2. Gather context -- Client types (browser, mobile, server), latency requirements, data flow direction, team expertise, existing infrastructure, cloud provider, scale expectations

3. Analyze -- Apply API design principles. Every protocol has trade-offs; never recommend without qualifying.

4. Recommend -- Actionable guidance with trade-offs, not a single answer

Protocol Paradigms

Request/Response (Client-Initiated)

Synchronous communication where the client sends a request and waits for a response. Best for CRUD operations, queries, and commands.

Protocol	Model	Data Format	Best For	Trade-offs
REST	Resource-oriented (HTTP verbs + URLs)	JSON (typically)	Public APIs, CDN-cacheable data, broad compatibility	Over-fetching/under-fetching, no standard query language
GraphQL	Query-based (single endpoint)	JSON	BFF layers, mobile apps, federated microservices	Caching complexity, query cost analysis required, POST-default
gRPC	RPC with binary encoding (HTTP/2)	Protocol Buffers	Internal microservices, polyglot systems, streaming	No browser support without proxy, binary debugging harder
OData	REST superset with query language	JSON	Enterprise data APIs, Power BI/Excel integration, Microsoft/SAP	Smaller ecosystem outside Microsoft, verbose URLs

Real-Time / Event-Driven (Server-Initiated or Bidirectional)

Persistent connections where data flows without explicit client requests. Best for live updates, notifications, and collaborative features.

Protocol	Direction	Transport	Best For	Trade-offs
WebSocket	Bidirectional	TCP (after HTTP upgrade)	Chat, gaming, trading, collaborative editing	No auto-reconnect, no rooms, proxy issues, sticky sessions
SSE	Server-to-client only	HTTP (standard)	LLM streaming, dashboards, notifications, log tailing	No client-to-server push, text-only (JSON serialized)
SignalR	Bidirectional (abstraction)	WS > SSE > Long Polling	.NET real-time apps, transport fallback needed	.NET server required, Azure dependency for managed scaling
Socket.IO	Bidirectional (abstraction)	WS > Long Polling	Node.js real-time apps, rooms/namespaces pattern	Custom protocol (not raw WS), larger payload overhead

Decision Framework

Step 1: What is the data flow pattern?

Pattern	Description	Protocols
Request/Response	Client asks, server answers	REST, GraphQL, gRPC, OData
Server Push	Server sends updates to client	SSE, WebSocket, SignalR, Socket.IO
Bidirectional	Both sides send freely	WebSocket, SignalR, Socket.IO, gRPC (bidi streaming)
Streaming	Continuous data flow	SSE, gRPC streaming, WebSocket

Step 2: Who is the client?

Client	Best Protocols	Avoid
Browser (public)	REST, GraphQL, SSE, WebSocket	gRPC (needs proxy)
Mobile app	REST, GraphQL (field selection), SSE	OData (complex for mobile)
Internal microservice	gRPC (performance), REST (simplicity)	GraphQL (overkill for service-to-service)
Enterprise tool (Excel, Power BI)	OData, REST	GraphQL (no native support)
IoT device	gRPC, WebSocket, MQTT	GraphQL (too heavy)

Step 3: What are the latency requirements?

Requirement	Protocol	Typical Latency
Sub-10ms message delivery	WebSocket (post-handshake)	0.5-10ms
Low-latency RPC	gRPC	10-50ms
Real-time push (acceptable 10-50ms)	SSE, WebSocket	10-50ms
Standard API calls	REST, GraphQL	50-300ms
Polling replacement	SSE (server push), Long Polling	10ms-500ms

Step 4: Infrastructure constraints?

Constraint	Impact	Recommendation
Corporate proxies blocking WebSocket	WS upgrade fails	SSE (works through all proxies) or SignalR/Socket.IO (automatic fallback)
CDN caching required	POST-based protocols not cached	REST (GET), GraphQL with persisted queries (GET)
No sticky sessions available	Stateful connections break	SSE (stateless reconnect), REST
HTTP/2 not available	gRPC requires HTTP/2	REST, GraphQL
Browser cannot set custom headers	WS/SSE handshake limited	Query string tokens, cookie auth

Step 5: Team and ecosystem alignment?

Team / Stack	Natural Fit
.NET / C# team	REST (ASP.NET Core), SignalR (real-time), gRPC (.NET native), OData (Microsoft ecosystem)
Node.js / TypeScript team	REST (Express/Fastify), GraphQL (Apollo), Socket.IO (real-time), SSE (native)
Python team	REST (FastAPI/Django), GraphQL (Strawberry), gRPC (grpcio), SSE (sse-starlette)
Go team	REST (net/http), gRPC (native), WebSocket (gorilla/websocket), SSE (net/http + Flusher)
Java / Kotlin team	REST (Spring Boot), gRPC (grpc-java), GraphQL (GraphQL Java), WebSocket (Spring)
Multi-language microservices	gRPC (code generation for all languages)

Multi-Protocol Architecture

Most production systems use multiple protocols at different layers:

External Clients (Browser, Mobile)
     |
     v
API Gateway (REST / GraphQL)        <-- Public-facing; broad compatibility
     |
     v
BFF / Aggregation Layer             <-- GraphQL Federation or REST aggregation
     |         |
     v         v
Service A    Service B               <-- Internal gRPC microservices
(gRPC)       (gRPC)
     |
     v
Event Bus (Kafka / SNS)              <-- Async event-driven side effects
     |
     v
Real-time Push (SSE / WebSocket)     <-- Client notifications

Pattern: REST or GraphQL at the edge (browser compatibility, caching), gRPC internally (performance, type safety), SSE or WebSocket for push (real-time updates).

Technology Comparison

Dimension	REST	GraphQL	gRPC	OData	WebSocket	SSE	SignalR	Socket.IO
Caching	Excellent (HTTP native)	Hard (POST default)	None (binary)	Good (HTTP GET)	None	None	None	None
Browser support	Universal	Universal	Proxy required	Universal	99%+	99%+	JS client	JS client
Schema/contract	OpenAPI	SDL (introspectable)	Protobuf (.proto)	CSDL ($metadata)	None (app-defined)	None	None	None
Payload efficiency	JSON (verbose)	JSON (precise fields)	Protobuf (3-10x smaller)	JSON (verbose)	App-defined	Text only	JSON or MessagePack	JSON + binary
Streaming	Chunked transfer	Subscriptions (WS)	4 streaming modes	No	Native	Native	Native	Native
Code generation	openapi-generator	GraphQL Codegen	protoc (all languages)	OData client gen	None	None	None	None
Auto-reconnect	N/A	N/A	N/A	N/A	No (manual)	Yes (built-in)	Yes	Yes

Anti-Patterns

1. "REST for everything" -- gRPC is better for internal service-to-service. GraphQL is better for complex client-driven queries. REST is great for public APIs and simple CRUD, not for every communication pattern.
2. "WebSocket for one-way server push" -- SSE is simpler, HTTP-native, auto-reconnects, and works through all proxies. Use WebSocket only when you need bidirectional communication.
3. "GraphQL for simple CRUD" -- If every query maps 1:1 to a database table with no joins, REST is simpler. GraphQL shines when clients need flexible data shapes from multiple sources.
4. "Polling instead of push" -- If you are polling every 5 seconds, use SSE or WebSocket. Polling wastes bandwidth and adds latency.
5. "Rolling your own real-time protocol" -- Building reconnection, rooms, presence, and backpressure from scratch on raw WebSocket is months of work. Use SignalR or Socket.IO unless you have specific requirements they cannot meet.
6. "Ignoring authentication differences across protocols" -- Browser WebSocket and SSE cannot set custom headers. Plan for query-string tokens or cookie-based auth from day one.
7. "Same API version strategy for all protocols" -- REST uses URL path versioning, GraphQL evolves schemas additively, gRPC uses field numbers. Each protocol has its own evolution model.

Cross-Domain References

Technology	Cross-Reference	When
Backend frameworks	skills/backend/SKILL.md	Framework-specific REST/API implementation (Express, FastAPI, ASP.NET Core)
Kafka	skills/etl/streaming/kafka/SKILL.md	Event streaming as async layer behind APIs
Database	skills/database/SKILL.md	Data layer behind APIs (query optimization, connection pooling)

Subcategory Routing

Request Pattern	Route To
Request/Response APIs
GraphQL, Apollo, Federation, schema design, DataLoader, Relay, Strawberry, Hot Chocolate	graphql/SKILL.md
gRPC, protobuf, proto3, streaming RPC, load balancing, health check, interceptors	grpc/SKILL.md
REST, OpenAPI, HTTP semantics, CORS, caching, API gateway, rate limiting, pagination	rest/SKILL.md
OData, $filter, $expand, $select, EDM, CSDL, batch, SAP, Power BI	odata/SKILL.md
Real-Time / Event-Driven
SignalR, hub, group, Azure SignalR Service, backplane, .NET real-time	signalr/SKILL.md
Socket.IO, rooms, namespaces, adapters, Engine.IO, scaling	socketio/SKILL.md
WebSocket, RFC 6455, ws, wss, close codes, frames, ping/pong	websocket/SKILL.md
SSE, Server-Sent Events, EventSource, text/event-stream, LLM streaming	sse/SKILL.md
Cross-Protocol
Protocol comparison, which protocol, REST vs GraphQL, WebSocket vs SSE	This agent (use tables above)
API authentication, JWT, OAuth, CORS, API keys	Load references/concepts.md
API versioning strategy	Load references/concepts.md
API gateway design	Load references/concepts.md

Reference Files

• references/concepts.md -- API design theory, authentication across protocols, versioning strategies, API gateway patterns, observability, error handling, idempotency, performance patterns. Read for architecture and design questions.
• references/paradigm-request-response.md -- When and why to use REST vs GraphQL vs gRPC vs OData. Detailed comparison with code examples and decision criteria. Read when evaluating request/response protocols.
• references/paradigm-realtime.md -- When and why to use WebSocket vs SSE vs SignalR vs Socket.IO. Transport comparison, scaling patterns, authentication constraints. Read when evaluating real-time technologies.