API Integration
Build robust, type-safe API clients from specs and documentation.
Key Principles
- Type everything — Runtime-validated types for all requests and responses
- Fail explicitly — No silent failures; throw typed errors with context
- Auth is first-class — Handle auth in the client layer, not scattered in calls
- Retry intelligently — Only idempotent methods, only transient failures, with backoff
- Isolate the boundary — Transform API shapes at the integration layer, not in app code
When NOT to Use
- Designing your own APIs — Use
api-designfor building endpoints others will consume - Writing API test suites — Use
testing-strategyfor test architecture, contract tests, mocking - Building SDKs for your API — Use
sdk-developmentfor packaging your own API as a client library
Quick Start Checklist
- Obtain API credentials and locate documentation (spec, docs, or examples)
- Analyze inputs: extract base URL, auth scheme, endpoints, error formats
- Choose architecture: typed wrapper (1-5 endpoints), service class (5-20), or generated client (20+)
- Implement types, client, auth handling, and error classification
- Add retry logic for transient failures and rate limit handling
- Write tests with mocked responses and error scenarios
References
| Reference | Description |
|---|---|
| openapi-specs-types.md | Parsing OpenAPI specs, type generation strategies |
| openapi-patterns-codegen.md | Common patterns, client generation, GraphQL, informal docs |
| client-base-service-layer.md | Base client, interceptors, service layer pattern |
| client-request-response-caching.md | Request config, response parsing, caching, logging |
| error-classification.md | Error type hierarchy, classification, response conversion |
| error-retry-circuit-breaker.md | Retry with backoff, rate limits, circuit breaker |
| error-fallback-patterns.md | Fallback strategies, Result type, error boundaries, reporting |
| auth-api-keys-bearer.md | API key and bearer token authentication |
| auth-oauth2.md | OAuth 2.0 authorization code, PKCE, client credentials |
| auth-jwt-hmac-storage.md | JWT handling, HMAC signatures, secure token storage |
| testing-mocking-fixtures.md | HTTP mocking (MSW, Nock), test fixtures |
| testing-unit-integration.md | Unit tests for transformers, integration tests for services |
| testing-contract-e2e-config.md | Contract testing, E2E tests, Jest configuration |