API Integration Patterns
Pick the protocol by data shape, ownership, and runtime constraints. Avoid mixing patterns without a clear boundary.
Selection Guide
-
REST:
-
Standard CRUD, broad client compatibility, simple caching.
-
GraphQL:
-
Flexible read models, multi-client data composition, schema governance.
-
WebSocket:
-
Bi-directional real-time channels with low-latency updates.
-
SSE:
-
Server-to-client streaming where client push is unnecessary.
-
tRPC:
-
End-to-end TypeScript contracts in monorepos.
Use This Skill When
-
You need to define or refactor API boundaries.
-
Frontend/server data fetching strategy is unclear.
-
Real-time transport choice is blocking implementation.
Implementation Workflow
- Define API Contract
-
Identify resource ownership and versioning strategy.
-
Define request/response shapes and error model.
-
Standardize auth, pagination, filtering, and idempotency.
- Choose Transport
-
REST for core CRUD.
-
GraphQL for query composition.
-
WebSocket/SSE for live updates.
-
tRPC when shared TS types are required and service boundary allows it.
- Standardize Client Layer
-
Central client factory and interceptors.
-
Typed API wrappers.
-
Uniform retries/timeouts and auth refresh logic.
-
Cache and invalidation rules documented per endpoint group.
- Error and Observability
-
Consistent API error envelope.
-
Correlation IDs and request tracing.
-
Log validation and transport failures separately.
- Security Baseline
-
Validate input schema at API boundary.
-
Enforce authz at resource/action level.
-
Apply rate limiting and payload size limits.
Output Requirements for Agent
-
Recommended transport and why.
-
Endpoint/schema proposal.
-
Client integration pattern.
-
Real-time model if needed.
-
Security and testing checklist.
References
- Full templates for REST, GraphQL, WebSocket, SSE, and tRPC: references/guide.md