chrishuffman5/overview

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.