Overview

---
name: overview
description: "Cross-protocol API and real-time communication strategy: protocol selection (REST vs GraphQL vs gRPC vs OData vs WebSocket vs SSE vs SignalR vs Socket.IO), API gateway design, versioning strategy, authentication across protocols, and multi-protocol architecture. Use when the question is strategic or comparative — \"API design\", \"which protocol\", \"REST vs GraphQL\", \"WebSocket vs SSE\", \"API gateway\", \"API versioning\", \"CORS\", \"protocol comparison\", \"real-time architecture\", \"multi-protocol architecture\". Do NOT use for technology-specific implementation questions (GraphQL resolvers, gRPC interceptors, SignalR hubs, etc.) — use the specific technology's skill instead."
license: MIT
---

# API & Real-Time Strategy

This skill covers cross-protocol API architecture: request/response APIs (REST, GraphQL, gRPC, OData), real-time transports (WebSocket, SSE, SignalR, Socket.IO), API gateway patterns, authentication, versioning, and protocol selection. For technology-specific implementation, read the relevant sibling skill directly.

## When to Use This Skill vs. a Technology Skill

**Use this skill 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"

**Read a technology skill directly when the question is technology-specific:**
- "GraphQL N+1 query problem with DataLoader" --> the `graphql` skill
- "gRPC interceptor chain ordering" --> the `grpc` skill
- "OpenAPI 3.1 spec validation" --> the `rest` skill
- "OData $filter with lambda operators" --> the `odata` skill
- "SignalR hub scaling with Redis backplane" --> the `signalr` skill
- "Socket.IO room broadcasting not reaching all clients" --> the `socketio` skill
- "WebSocket close codes and reconnection" --> the `websocket` skill
- "SSE auto-reconnect with Last-Event-ID" --> the `sse` skill

## 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** -- Read the relevant technology skill directly

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-Plugin References

| Technology | Plugin / Skill | When |
|---|---|---|
| Backend frameworks | `backend` plugin | Framework-specific REST/API implementation (Express, FastAPI, ASP.NET Core) |
| Kafka | `messaging` plugin, `kafka` skill | Event streaming as async layer behind APIs |
| Database | `database` plugin | 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 |
| gRPC, protobuf, proto3, streaming RPC, load balancing, health check, interceptors | `grpc` skill |
| REST, OpenAPI, HTTP semantics, CORS, caching, API gateway, rate limiting, pagination | `rest` skill |
| OData, $filter, $expand, $select, EDM, CSDL, batch, SAP, Power BI | `odata` skill |
| **Real-Time / Event-Driven** | |
| SignalR, hub, group, Azure SignalR Service, backplane, .NET real-time | `signalr` skill |
| Socket.IO, rooms, namespaces, adapters, Engine.IO, scaling | `socketio` skill |
| WebSocket, RFC 6455, ws, wss, close codes, frames, ping/pong | `websocket` skill |
| SSE, Server-Sent Events, EventSource, text/event-stream, LLM streaming | `sse` skill |
| **Cross-Protocol** | |
| Protocol comparison, which protocol, REST vs GraphQL, WebSocket vs SSE | This skill (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.