Third-Party API Integration Best Practices

You implement robust integrations with third-party APIs that handle failure gracefully, respect rate limits, and remain maintainable.

## Integration Architecture
Structure every API integration as a dedicated module:
- **Client layer** — HTTP client, auth, base URL, headers (thin wrapper around fetch/axios)
- **Service layer** — business operations using the client (what, not how)
- **Types layer** — response/request types matching the API schema
- **Error layer** — typed errors for each failure mode

## Authentication Patterns
- Store API keys in environment variables — never hardcode
- Use a secrets manager for production (not .env files)
- Implement token refresh automatically — don't expose token expiry to callers
- For OAuth flows, store access and refresh tokens separately with correct TTLs

## Error Handling
Map API errors to domain errors with context:
```typescript
try {
  return await apiClient.post('/charges', payload);
} catch (err) {
  if (err.status === 402) throw new PaymentDeclinedError(err.message, payload.amount);
  if (err.status === 429) throw new RateLimitError(err.headers['retry-after']);
  throw new ExternalServiceError('payment', err);
}
```

## Rate Limiting
- Read the API's rate limit headers on every response
- Implement exponential backoff with jitter for 429 responses
- Use a request queue to prevent burst traffic
- Track rate limit consumption proactively, not reactively

## Reliability Patterns
- **Timeouts**: set explicit timeouts on every request (default: 10s, adjust per endpoint)
- **Retries**: retry on 5xx and network errors, not on 4xx (except 429)
- **Circuit breaker**: stop hammering a failing API — open the circuit after N failures
- **Idempotency keys**: use idempotency keys for write operations to safely retry

## Webhook Handling
- Verify webhook signatures before processing — never trust unverified webhooks
- Return 200 immediately, process asynchronously in a background job
- Implement idempotent handlers — the same event may arrive multiple times
- Replay missed webhooks by periodically syncing state with the API

## Testing Integrations
- Use the API's sandbox/test environment for integration tests
- Record real API responses with VCR for deterministic unit tests
- Test all error cases — don't just test the happy path
- Mock the entire API client in unit tests, not individual HTTP calls

## Monitoring
- Log every external API call with: endpoint, duration, status code
- Set up alerts on elevated error rates or latency spikes
- Track API usage against quotas and budget limits

Переменные

Цели экспорта

Используется в паках