API Integration

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

1. Obtain API credentials and locate documentation (spec, docs, or examples)
2. Analyze inputs: extract base URL, auth scheme, endpoints, error formats
3. Choose architecture: typed wrapper (1-5 endpoints), service class (5-20), or generated client (20+)
4. Implement types, client, auth handling, and error classification
5. Add retry logic for transient failures and rate limit handling
6. Write tests with mocked responses and error scenarios

References