api-integration-example

API Integration (Example)

Summary

Defines consistent patterns for integrating with external APIs including error handling, retry logic, caching, and data transformation. This is an example template.

Context

API integrations are critical points of failure and complexity. Consistent patterns ensure reliability, maintainability, and good user experience even when external services have issues.

Instructions

API Client Structure

• Base Client: Common configuration, headers, interceptors
• Service Clients: Specific API endpoints and methods
• Error Handling: Consistent error types and recovery
• Retry Logic: Exponential backoff for transient failures
• Caching: Appropriate caching strategies per endpoint

Request/Response Flow

1. Request Preparation

   • Validate input parameters
   • Add authentication headers
   • Apply request transformations
   • Log request details (non-sensitive)

2. Request Execution

   • Execute with timeout
   • Handle network errors
   • Implement retry logic
   • Monitor request performance

3. Response Processing

   • Validate response structure
   • Transform data format
   • Cache when appropriate
   • Log response details

Examples

Base API Client

class BaseApiClient {
  private baseURL: string;
  private defaultTimeout: number = 10000;
  
  constructor(baseURL: string) {
    this.baseURL = baseURL;
  }
  
  async request<T>(
    endpoint: string, 
    options: RequestOptions = {}
  ): Promise<ApiResponse<T>> {
    const config = {
      method: options.method || 'GET',
      headers: {
        'Content-Type': 'application/json',
        ...this.getAuthHeaders(),
        ...options.headers
      },
      timeout: options.timeout || this.defaultTimeout,
      body: options.body ? JSON.stringify(options.body) : undefined
    };
    
    try {
      const response = await this.executeWithRetry(
        `${this.baseURL}${endpoint}`, 
        config,
        options.retryOptions
      );
      
      return this.processResponse<T>(response);
    } catch (error) {
      throw this.handleError(error, endpoint);
    }
  }
  
  private async executeWithRetry(
    url: string, 
    config: RequestConfig,
    retryOptions?: RetryOptions
  ): Promise<Response> {
    const maxRetries = retryOptions?.maxRetries || 3;
    const backoffMs = retryOptions?.backoffMs || 1000;
    
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetch(url, config);
        
        if (response.ok || !this.isRetryableError(response.status)) {
          return response;
        }
        
        if (attempt === maxRetries) {
          throw new ApiError('Max retries exceeded', response.status);
        }
        
        await this.delay(backoffMs * Math.pow(2, attempt));
      } catch (error) {
        if (attempt === maxRetries || !this.isRetryableError(error)) {
          throw error;
        }
        
        await this.delay(backoffMs * Math.pow(2, attempt));
      }
    }
  }
}