Designing API Client SDKs

A well-designed SDK makes API integration effortless. A poorly designed one causes frustration and support burden. Here's how to build SDKs developers love.

SDK Architecture#

// Clean, intuitive structure
import { Client } from '@yourcompany/sdk';

const client = new Client({
  apiKey: process.env.API_KEY,
  baseUrl: 'https://api.example.com', // Optional override
});

// Resource-based organization
const user = await client.users.get('user_123');
const orders = await client.orders.list({ userId: user.id });
const newOrder = await client.orders.create({ items: [...] });

// Fluent interface for complex queries
const results = await client.products
  .list()
  .filter({ category: 'electronics' })
  .sort('price', 'asc')
  .limit(20)
  .execute();

Core Client Implementation#

interface ClientConfig {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
  retries?: number;
}

class Client {
  private config: Required<ClientConfig>;
  private http: HttpClient;

  // Resource accessors
  readonly users: UsersResource;
  readonly orders: OrdersResource;
  readonly products: ProductsResource;

  constructor(config: ClientConfig) {
    this.config = {
      baseUrl: 'https://api.example.com/v1',
      timeout: 30000,
      retries: 3,
      ...config,
    };

    this.http = new HttpClient(this.config);

    // Initialize resources
    this.users = new UsersResource(this.http);
    this.orders = new OrdersResource(this.http);
    this.products = new ProductsResource(this.http);
  }
}

// HTTP client with common functionality
class HttpClient {
  constructor(private config: Required<ClientConfig>) {}

  async request<T>(options: RequestOptions): Promise<T> {
    const response = await this.executeWithRetry(options);
    return this.handleResponse<T>(response);
  }

  private async executeWithRetry(options: RequestOptions): Promise<Response> {
    let lastError: Error;

    for (let attempt = 0; attempt <= this.config.retries; attempt++) {
      try {
        const controller = new AbortController();
        const timeoutId = setTimeout(
          () => controller.abort(),
          this.config.timeout
        );

        const response = await fetch(`${this.config.baseUrl}${options.path}`, {
          method: options.method,
          headers: {
            'Authorization': `Bearer ${this.config.apiKey}`,
            'Content-Type': 'application/json',
            'User-Agent': `yourcompany-sdk/1.0.0`,
            ...options.headers,
          },
          body: options.body ? JSON.stringify(options.body) : undefined,
          signal: controller.signal,
        });

        clearTimeout(timeoutId);

        if (response.ok || !this.isRetryable(response.status)) {
          return response;
        }

        lastError = new ApiError(response.status, await response.text());
      } catch (error) {
        lastError = error as Error;
      }

      if (attempt < this.config.retries) {
        await this.delay(Math.pow(2, attempt) * 1000);
      }
    }

    throw lastError!;
  }

  private isRetryable(status: number): boolean {
    return status === 429 || status >= 500;
  }

  private delay(ms: number): Promise<void> {
    return new Promise((resolve) => setTimeout(resolve, ms));
  }

  private async handleResponse<T>(response: Response): Promise<T> {
    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new ApiError(response.status, error.message, error.code);
    }

    return response.json();
  }
}

Resource Classes#

// Base resource with common operations
abstract class Resource<T, CreateInput, UpdateInput> {
  constructor(protected http: HttpClient, protected basePath: string) {}

  async get(id: string): Promise<T> {
    return this.http.request<T>({
      method: 'GET',
      path: `${this.basePath}/${id}`,
    });
  }

  async list(params?: ListParams): Promise<PaginatedResponse<T>> {
    return this.http.request<PaginatedResponse<T>>({
      method: 'GET',
      path: this.basePath,
      query: params,
    });
  }

  async create(data: CreateInput): Promise<T> {
    return this.http.request<T>({
      method: 'POST',
      path: this.basePath,
      body: data,
    });
  }

  async update(id: string, data: UpdateInput): Promise<T> {
    return this.http.request<T>({
      method: 'PATCH',
      path: `${this.basePath}/${id}`,
      body: data,
    });
  }

  async delete(id: string): Promise<void> {
    await this.http.request<void>({
      method: 'DELETE',
      path: `${this.basePath}/${id}`,
    });
  }
}

// Specific resource with custom methods
class UsersResource extends Resource<User, CreateUserInput, UpdateUserInput> {
  constructor(http: HttpClient) {
    super(http, '/users');
  }

  async getByEmail(email: string): Promise<User | null> {
    const result = await this.list({ email });
    return result.data[0] || null;
  }

  async updatePassword(id: string, password: string): Promise<void> {
    await this.http.request({
      method: 'POST',
      path: `${this.basePath}/${id}/password`,
      body: { password },
    });
  }

  async listOrders(userId: string): Promise<Order[]> {
    return this.http.request({
      method: 'GET',
      path: `${this.basePath}/${userId}/orders`,
    });
  }
}

Error Handling#

// Custom error types
class ApiError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public code?: string,
    public details?: Record<string, any>
  ) {
    super(message);
    this.name = 'ApiError';
  }

  static isApiError(error: unknown): error is ApiError {
    return error instanceof ApiError;
  }
}

class ValidationError extends ApiError {
  constructor(
    message: string,
    public errors: { field: string; message: string }[]
  ) {
    super(400, message, 'VALIDATION_ERROR', { errors });
    this.name = 'ValidationError';
  }
}

class RateLimitError extends ApiError {
  constructor(public retryAfter: number) {
    super(429, 'Rate limit exceeded', 'RATE_LIMITED', { retryAfter });
    this.name = 'RateLimitError';
  }
}

// Usage
try {
  await client.users.create({ email: 'invalid' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation errors:', error.errors);
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (ApiError.isApiError(error)) {
    console.log(`API error: ${error.statusCode} - ${error.message}`);
  }
}

Pagination#

// Async iterator for pagination
class UsersResource {
  async *listAll(params?: ListParams): AsyncGenerator<User> {
    let cursor: string | undefined;

    do {
      const response = await this.list({ ...params, cursor });

      for (const user of response.data) {
        yield user;
      }

      cursor = response.pagination.nextCursor;
    } while (cursor);
  }
}

// Usage
for await (const user of client.users.listAll({ role: 'admin' })) {
  console.log(user.email);
}

// Collect all
const allUsers: User[] = [];
for await (const user of client.users.listAll()) {
  allUsers.push(user);
}

TypeScript Types#

// Export all types for consumers
export interface User {
  id: string;
  email: string;
  name: string;
  role: 'user' | 'admin';
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateUserInput {
  email: string;
  name: string;
  role?: 'user' | 'admin';
}

export interface UpdateUserInput {
  email?: string;
  name?: string;
  role?: 'user' | 'admin';
}

export interface ListParams {
  limit?: number;
  cursor?: string;
  sort?: string;
  order?: 'asc' | 'desc';
}

export interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    hasMore: boolean;
    nextCursor?: string;
  };
}

// Re-export from index
export { Client, ClientConfig } from './client';
export { ApiError, ValidationError, RateLimitError } from './errors';
export * from './types';

Testing Utilities#

// Mock client for testing
export function createMockClient(): jest.Mocked<Client> {
  return {
    users: {
      get: jest.fn(),
      list: jest.fn(),
      create: jest.fn(),
      update: jest.fn(),
      delete: jest.fn(),
    },
    orders: {
      get: jest.fn(),
      list: jest.fn(),
      create: jest.fn(),
    },
  } as unknown as jest.Mocked<Client>;
}

// Test helpers
export function mockUser(overrides?: Partial<User>): User {
  return {
    id: 'user_123',
    email: 'test@example.com',
    name: 'Test User',
    role: 'user',
    createdAt: new Date('2024-01-01'),
    updatedAt: new Date('2024-01-01'),
    ...overrides,
  };
}

// Usage in tests
describe('UserService', () => {
  it('creates user correctly', async () => {
    const mockClient = createMockClient();
    mockClient.users.create.mockResolvedValue(mockUser());

    const service = new UserService(mockClient);
    const user = await service.createUser({ email: 'test@example.com', name: 'Test' });

    expect(mockClient.users.create).toHaveBeenCalledWith({
      email: 'test@example.com',
      name: 'Test',
    });
    expect(user.id).toBe('user_123');
  });
});

Best Practices#

Design:
✓ Consistent naming conventions
✓ Intuitive method signatures
✓ Full TypeScript support
✓ Comprehensive error types

Reliability:
✓ Automatic retries
✓ Configurable timeouts
✓ Rate limit handling
✓ Connection pooling

Developer Experience:
✓ Clear documentation
✓ Code examples
✓ Testing utilities
✓ Changelog

A great SDK feels like a natural extension of the language. Focus on intuitive design, strong typing, proper error handling, and excellent documentation. Provide testing utilities and keep the SDK updated with your API.