API Integration

Build robust, type-safe API clients from specs and documentation.

Integration Workflow

┌─────────────────────────────────────────────────────────────┐
│                         INPUTS                              │
├──────────────┬──────────────┬──────────────┬────────────────┤
│ OpenAPI/     │ GraphQL      │ REST Docs    │ Example        │
│ Swagger      │ Schema       │ (informal)   │ Requests       │
└──────┬───────┴──────┬───────┴──────┬───────┴───────┬────────┘
       │              │              │               │
       └──────────────┴──────────────┴───────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │      ANALYSIS & DESIGN        │
              │  • Extract types/schemas      │
              │  • Identify auth requirements │
              │  • Map error responses        │
              │  • Plan client architecture   │
              └───────────────┬───────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │       IMPLEMENTATION          │
              │  • Generate/write types       │
              │  • Build client layer         │
              │  • Implement auth flow        │
              │  • Add error handling         │
              │  • Configure retry logic      │
              └───────────────┬───────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │         TESTING               │
              │  • Mock responses             │
              │  • Integration tests          │
              │  • Error scenario tests       │
              └───────────────────────────────┘

Input Analysis

OpenAPI/Swagger

Best case: Full spec with schemas, auth, error responses.

Extract:

• Base URL(s) and environments
• Authentication schemes
• Endpoint paths and methods
• Request/response schemas
• Error response formats
• Rate limit headers

GraphQL

Extract:

• Schema types and operations
• Authentication headers
• Error format (errors array)
• Pagination patterns (cursor, offset)

Informal REST Docs

When no formal spec exists:

1. Document observed endpoints
2. Infer types from examples
3. Test edge cases to discover error formats
4. Note undocumented behaviors

Example Requests

From cURL, Postman, or code samples:

1. Extract base URL, headers, auth pattern
2. Infer request/response types
3. Note required vs optional fields
4. Identify query params vs body

Client Architecture Decision

How complex is the integration?
│
├── Simple (1-5 endpoints, basic auth)
│   └── Typed fetch wrapper
│
├── Medium (5-20 endpoints, OAuth/multiple resources)
│   └── Service class with methods per endpoint
│
└── Complex (20+ endpoints, multiple auth schemes, heavy usage)
    └── Generated client + custom wrapper layer

Architecture Quick Reference

Complexity	Pattern	When to Use
Simple	Typed functions	Few endpoints, one-off integration
Medium	Service class	Core integration, team will maintain
Complex	Generated + wrapper	Large API, frequent updates, critical path

Core Principles

1. Type Everything

// ❌ Untyped
const user = await api.get('/users/1');

// ✅ Typed
const user = await api.get<User>('/users/1');

// ✅ Even better: validated at runtime
const user = await api.get('/users/1', { schema: UserSchema });

2. Fail Explicitly

// ❌ Silent failure
const data = response.data ?? {};

// ✅ Explicit error
if (!response.ok) {
  throw new ApiError(response.status, await response.json());
}

3. Auth is a First-Class Concern

// ❌ Auth scattered everywhere
fetch(url, { headers: { Authorization: `Bearer ${token}` } });

// ✅ Auth handled by client
const client = createApiClient({ auth: tokenProvider });

4. Retry Intelligently

// ❌ Retry everything
retry(request, { attempts: 3 });

// ✅ Retry only idempotent + transient failures
retry(request, {
  attempts: 3,
  when: (error) => error.status >= 500 || error.code === 'NETWORK_ERROR',
  methods: ['GET', 'PUT', 'DELETE'], // Not POST
});

5. Isolate the Integration

// ❌ API details leak everywhere
const response = await fetch(`${API_URL}/users/${id}`);
const user = response.data.data.attributes;

// ✅ Transform at boundary
// In api client:
async getUser(id: string): Promise<User> {
  const response = await this.get(`/users/${id}`);
  return transformUser(response.data);
}

Quick Patterns

Typed Fetch Wrapper

async function api<T>(
  path: string,
  options?: RequestInit
): Promise<T> {
  const response = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    throw await ApiError.fromResponse(response);
  }

  return response.json();
}

// Usage
const user = await api<User>('/users/1');

Service Class

class UserService {
  constructor(private client: ApiClient) {}

  async getUser(id: string): Promise<User> {
    return this.client.get(`/users/${id}`);
  }

  async createUser(data: CreateUserInput): Promise<User> {
    return this.client.post('/users', data);
  }

  async updateUser(id: string, data: UpdateUserInput): Promise<User> {
    return this.client.put(`/users/${id}`, data);
  }

  async deleteUser(id: string): Promise<void> {
    return this.client.delete(`/users/${id}`);
  }
}

Error Classification

class ApiError extends Error {
  constructor(
    public status: number,
    public code: string,
    public details?: unknown
  ) {
    super(`API Error: ${code}`);
  }

  get isRetryable(): boolean {
    return this.status >= 500 || this.status === 429;
  }

  get isAuthError(): boolean {
    return this.status === 401 || this.status === 403;
  }

  get isValidationError(): boolean {
    return this.status === 400 || this.status === 422;
  }

  get isNotFound(): boolean {
    return this.status === 404;
  }
}

Anti-Patterns

❌ Stringly-Typed APIs

// Bad: No type safety
const user = await api.get('/users/' + id);
user.nmae; // Typo not caught

❌ Swallowing Errors

// Bad: Errors disappear
try {
  return await api.getUser(id);
} catch {
  return null;
}

❌ Hardcoded Auth

// Bad: Can't refresh, can't test
const headers = { Authorization: 'Bearer abc123' };

❌ Retry Without Backoff

// Bad: Hammers failing server
while (attempts < 3) {
  try { return await request(); } catch { attempts++; }
}

❌ No Request/Response Logging

// Bad: Can't debug production issues
// No logging at all

❌ Mixing API Shapes with Domain Models

// Bad: API response shape leaks into app
function UserProfile({ user }: { user: ApiUserResponse }) {
  return <div>{user.data.attributes.name}</div>;
}

Implementation Checklist

Before Starting

• Obtained API credentials/keys
• Located API documentation (spec, docs, examples)
• Identified authentication method
• Understood rate limits
• Identified error response format

Client Implementation

• Types generated/defined for all endpoints
• Base client with auth handling
• Error class with classification
• Retry logic for transient failures
• Request/response logging (redacted)
• Timeout configuration

Error Handling

• All error responses typed
• Retry logic for 5xx and network errors
• Auth refresh on 401 (if applicable)
• Rate limit handling (429)
• Graceful degradation strategy

Testing

• Mocks for all endpoints
• Error scenario tests
• Auth flow tests
• Retry logic tests
• Integration test with real API (CI)

---

References:

• references/openapi-consumption.md — Parsing specs, type generation, codegen tools
• references/client-architecture.md — Client patterns, service layers, request handling
• references/error-handling.md — Error types, retry logic, circuit breakers
• references/authentication.md — OAuth, API keys, JWT, token refresh
• references/testing.md — Mocking, integration tests, contract testing