API Protocol Selection MOC
API Protocol Selection MOC
Navigation hub for four API protocol design notes. Use the decision flowchart below to select the right protocol, or browse by protocol family. See Design-Patterns-MOC for the root vault entry point.
REST and Operational Contracts
| Pattern | Intent | Use When |
|---|---|---|
| REST-API-Design | Design HTTP APIs using Richardson Maturity Model levels, RFC 9457 error contracts, versioning strategies, and OpenAPI contract-first workflow. | Public API for browser SPAs or third-party clients; need curl-testable, OpenAPI-documented endpoints |
| Operational-API-Patterns | Cross-protocol operational contracts: cursor pagination, idempotency keys, rate limiting response contracts, partial responses. | Any API protocol needs pagination, retry-safe mutations, or rate limiting contracts |
REST selection guide: REST is the default choice for public-facing APIs and unknown consumers. Start here unless you have a specific reason to use GraphQL or gRPC. Add Operational-API-Patterns contracts (pagination, idempotency keys, rate limiting) to any REST API serving production traffic.
Alternative Protocols
| Pattern | Intent | Use When |
|---|---|---|
| GraphQL-API-Design | Schema-first API design with client-defined field selection, N+1/DataLoader batching, and optional Federation for distributed graphs. | Clients need flexible field selection from graph-shaped data; team has DataLoader expertise |
| gRPC-Service-Design | Contract-first RPC using protobuf with four streaming types (unary, server, client, bidi), deadline propagation, and interceptors. | Internal service-to-service communication requiring streaming, binary performance, or polyglot client generation |
Alternative protocol selection guide: GraphQL and gRPC solve specific problems that REST does not address well. GraphQL eliminates over-fetching for graph-shaped data but introduces N+1 complexity. gRPC provides binary performance and native streaming but requires protobuf toolchain and a proxy for browser clients. Neither is a general-purpose REST replacement.
Protocol Comparison
| Dimension | REST | GraphQL | gRPC | WebSocket |
|---|---|---|---|---|
| Query flexibility | Fixed endpoints | Client-defined field selection | Fixed .proto methods | N/A -- persistent channel |
| Streaming | No (SSE for server-push) | Subscriptions (graphql-ws) | 4 native types (unary, server, client, bidi) | Bidirectional persistent |
| Contract | OpenAPI/JSON | SDL (schema-first) | .proto (code-first from contract) | Custom protocol |
| Client requirement | HTTP client | GraphQL client + DataLoader | Generated stub (protobuf toolchain) | WebSocket client |
| Browser support | Universal | Universal | gRPC-Web + proxy required | Universal |
| Public API fit | Excellent | Good (with complexity controls) | Poor (toolchain burden on third parties) | Situational |
| Performance | Medium (JSON, HTTP/1.1 or 2) | Medium (JSON, resolver overhead) | High (protobuf, HTTP/2 multiplexing) | High (persistent, low-overhead frames) |
| Complexity | Low | Medium-High (N+1, schema, cost) | Medium (proto schema, codegen) | Low (but protocol design falls to you) |
Protocol Selection -- Start Here
Are your consumers browser-based SPAs or unknown third-party clients? -> Yes: REST-API-Design (universal HTTP contract, curl-testable, OpenAPI tooling) -> No: Continue
Do clients need to select arbitrary subsets of fields from deeply nested or graph-shaped data? -> Yes, and team has DataLoader expertise: GraphQL-API-Design -> No: Continue
Is this internal service-to-service communication with streaming, binary performance, or polyglot client needs? -> Yes: gRPC-Service-Design -> No: Continue
Is this a real-time bidirectional channel (live feed, collaborative UI, game state)? -> Yes: WebSocket (see BFF-Pattern for SSE as simpler server-push alternative) -> No: Default to REST-API-Design -- HTTP request-response is sufficient
Backlinks
Sources
Protocol selection criteria drawn from the atomic notes: REST-API-Design, Operational-API-Patterns, GraphQL-API-Design, gRPC-Service-Design.