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-design for building endpoints others will consume
-
Writing API test suites — Use testing-strategy for test architecture, contract tests, mocking
-
Building SDKs for your API — Use sdk-development for 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