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

1. Define API Contract

• Identify resource ownership and versioning strategy.

• Define request/response shapes and error model.

• Standardize auth, pagination, filtering, and idempotency.

2. 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.

3. 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.

4. Error and Observability

• Consistent API error envelope.

• Correlation IDs and request tracing.

• Log validation and transport failures separately.

5. 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