Designing Sdks

SDK Design

Design client libraries (SDKs) with excellent developer experience through intuitive APIs, robust error handling, automatic retries, and consistent patterns across programming languages.

When to Use This Skill

Use when building a client library for a REST API, creating internal service SDKs, implementing retry logic with exponential backoff, handling authentication patterns, creating typed error hierarchies, implementing pagination with async iterators, or designing streaming APIs for real-time data.

Core Architecture Patterns

Client → Resources → Methods

Organize SDK code hierarchically:

Client (config: API key, base URL, retries, timeout)
├─ Resources (users, payments, posts)
│   ├─ create(), retrieve(), update(), delete()
│   └─ list() (with pagination)
└─ Top-Level Methods (convenience)

Resource-Based (Stripe style):

const client = new APIClient({ apiKey: 'sk_test_...' })
const user = await client.users.create({ email: 'user@example.com' })

Use for APIs <100 methods. Prioritizes developer experience.

Command-Based (AWS SDK v3):

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
await client.send(new PutObjectCommand({ Bucket: '...' }))

Use for APIs >100 methods. Prioritizes bundle size and tree-shaking.

For detailed architectural guidance, see references/architecture-patterns.md.

Language-Specific Patterns

TypeScript: Async-Only

const user = await client.users.create({ email: 'user@example.com' })

All methods return Promises. Avoid callbacks.

Python: Dual Sync/Async

# Sync
client = APIClient(api_key='sk_test_...')
user = client.users.create(email='user@example.com')

# Async
async_client = AsyncAPIClient(api_key='sk_test_...')
user = await async_client.users.create(email='user@example.com')

Provide both clients. Users choose based on architecture.

Go: Sync with Context

client := apiclient.New("api_key")
user, err := client.Users().Create(ctx, req)

Use context.Context for timeout and cancellation.

Authentication

API Key (Most Common)

const client = new APIClient({ apiKey: process.env.API_KEY })

Store keys in environment variables, never hardcode.

OAuth Token Refresh

const client = new APIClient({
  clientId: 'id',
  clientSecret: 'secret',
  refreshToken: 'token',
  onTokenRefresh: (newToken) => saveToken(newToken)
})

SDK automatically refreshes tokens before expiry.

Bearer Token Per-Request

await client.users.list({
  headers: { Authorization: `Bearer ${userToken}` }
})

Use for multi-tenant applications.

See references/authentication.md for OAuth flows, JWT handling, and credential providers.

Retry and Backoff

Exponential Backoff with Jitter

async function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries: number): Promise<T> {
  let attempt = 0

  while (attempt <= maxRetries) {
    try {
      return await fn()
    } catch (error) {
      attempt++
      if (attempt > maxRetries || !isRetryable(error)) throw error

      const exponential = Math.min(1000 * Math.pow(2, attempt - 1), 10000)
      const jitter = Math.random() * 500
      await sleep(exponential + jitter)
    }
  }
}

function isRetryable(error: any): boolean {
  return (
    error.code === 'ECONNRESET' ||
    error.code === 'ETIMEDOUT' ||
    (error.status >= 500 && error.status < 600) ||
    error.status === 429
  )
}

Retry Decision Matrix:

Rate Limit Handling

if (error.status === 429) {
  const retryAfter = parseInt(error.headers['retry-after'] || '60')
  await sleep(retryAfter * 1000)
}

Respect Retry-After header on 429 responses.

See references/retry-backoff.md for jitter strategies, circuit breakers, and idempotency keys.

Error Handling

Typed Error Hierarchy

class APIError extends Error {
  constructor(
    message: string,
    public status: number,
    public code: string,
    public requestId: string
  ) {
    super(message)
    this.name = 'APIError'
  }
}

class RateLimitError extends APIError {
  constructor(message: string, requestId: string, public retryAfter: number) {
    super(message, 429, 'rate_limit_error', requestId)
  }
}

class AuthenticationError extends APIError {
  constructor(message: string, requestId: string) {
    super(message, 401, 'authentication_error', requestId)
  }
}

Error Handling in Practice

try {
  const user = await client.users.create({ email: 'invalid' })
} catch (error) {
  if (error instanceof RateLimitError) {
    await sleep(error.retryAfter * 1000)
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key')
  } else if (error instanceof APIError) {
    console.error(`${error.message} (Request ID: ${error.requestId})`)
  }
}

Include request ID in all errors for debugging.

See references/error-handling.md for user-friendly messages, validation errors, and debugging support.

Pagination

Async Iterators (Recommended)

TypeScript:

for await (const user of client.users.list({ limit: 100 })) {
  console.log(user.id, user.email)
}

Python:

async for user in client.users.list(limit=100):
    print(user.id, user.email)

SDK automatically fetches next page.

Implementation

class UsersResource {
  async *list(options?: { limit?: number }): AsyncGenerator<User> {
    let cursor: string | undefined = undefined

    while (true) {
      const response = await this.client.request('GET', '/users', {
        query: { limit: String(options?.limit || 100), ...(cursor ? { cursor } : {}) }
      })

      for (const user of response.data) yield user

      if (!response.has_more) break
      cursor = response.next_cursor
    }
  }
}

Manual Pagination

let cursor: string | undefined = undefined
while (true) {
  const response = await client.users.list({ limit: 100, cursor })
  for (const user of response.data) console.log(user.id)
  if (!response.has_more) break
  cursor = response.next_cursor
}

Provide both automatic and manual options.

See references/pagination.md for cursor vs. offset pagination and Go channel patterns.

Streaming

Server-Sent Events

async *stream(path: string, body?: any): AsyncGenerator<any> {
  const response = await fetch(url, {
    headers: { 'Accept': 'text/event-stream' },
    body: JSON.stringify(body)
  })

  const reader = response.body!.getReader()
  const decoder = new TextDecoder()

  while (true) {
    const { done, value } = await reader.read()
    if (done) break

    const chunk = decoder.decode(value)
    for (const line of chunk.split('\n')) {
      if (line.startsWith('data: ')) {
        const data = line.slice(6)
        if (data === '[DONE]') return
        yield JSON.parse(data)
      }
    }
  }
}

// Usage
for await (const chunk of client.posts.stream({ prompt: 'Write a story' })) {
  process.stdout.write(chunk.content)
}

Idempotency Keys

Prevent duplicate operations during retries:

import { randomUUID } from 'crypto'

if (['POST', 'PATCH', 'PUT'].includes(method)) {
  headers['Idempotency-Key'] = options?.idempotencyKey || randomUUID()
}

// Usage
await client.charges.create(
  { amount: 1000 },
  { idempotencyKey: 'charge_unique_123' }
)

Server deduplicates requests by key.

Versioning

Semantic Versioning

• 1.0.0 → 1.1.0: New features (safe)
• 1.1.0 → 2.0.0: Breaking changes (review)
• 1.0.0 → 1.0.1: Bug fixes (safe)

Deprecation Warnings

function deprecated(message: string, since: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value
    descriptor.value = function (...args: any[]) {
      console.warn(`[DEPRECATED] ${propertyKey} since ${since}. ${message}`)
      return originalMethod.apply(this, args)
    }
    return descriptor
  }
}

@deprecated('Use users.list() instead', 'v2.0.0')
async getAll() { return this.list() }

API Version Pinning

const client = new APIClient({
  apiKey: 'sk_test_...',
  apiVersion: '2025-01-01'
})

See references/versioning.md for migration strategies.

Configuration Best Practices

interface ClientConfig {
  apiKey: string
  baseURL?: string
  maxRetries?: number
  timeout?: number
  apiVersion?: string
  onTokenRefresh?: (token: string) => void
}

class APIClient {
  constructor(config: ClientConfig) {
    this.apiKey = config.apiKey
    this.baseURL = config.baseURL || 'https://api.example.com'
    this.maxRetries = config.maxRetries ?? 3
    this.timeout = config.timeout ?? 30000
  }
}

Provide sensible defaults, require only apiKey.

Quick Reference Tables

Authentication Patterns

Retry Strategies

Pagination Options

Reference Documentation

Architecture:

• references/architecture-patterns.md - Resource vs. command organization

Core Patterns:

• references/authentication.md - OAuth, token refresh, credential providers
• references/retry-backoff.md - Exponential backoff, jitter, circuit breakers
• references/error-handling.md - Error hierarchies, debugging support
• references/pagination.md - Cursor vs. offset, async iterators
• references/versioning.md - SemVer, deprecation strategies
• references/testing-sdks.md - Unit testing, mocking, integration tests

Code Examples

TypeScript:

• examples/typescript/basic-client.ts - Simple async SDK
• examples/typescript/advanced-client.ts - Retry, errors, streaming
• examples/typescript/resource-based.ts - Stripe-style organization

Python:

• examples/python/sync-client.py - Synchronous client
• examples/python/async-client.py - Async client with asyncio
• examples/python/dual-client.py - Both sync and async

Go:

• examples/go/basic-client.go - Simple Go client
• examples/go/context-client.go - Context patterns
• examples/go/channel-pagination.go - Channel-based pagination

Best-in-Class SDK Examples

Study these production SDKs:

TypeScript/JavaScript:

• AWS SDK v3 (@aws-sdk/client-*): Modular, tree-shakeable, middleware
• Stripe Node (stripe): Resource-based, typed errors, excellent DX
• OpenAI Node (openai): Streaming, async iterators, modern TypeScript

Python:

• Boto3 (boto3): Resource vs. client patterns, paginators
• Stripe Python (stripe): Dual sync/async, context managers

Go:

• AWS SDK Go v2 (github.com/aws/aws-sdk-go-v2): Context, middleware

Common Pitfalls

Avoid these mistakes:

1. No Retry Logic - All SDKs need automatic retries for transient errors 2. Poor Error Messages - Include request ID, status code, error type 3. No Pagination - Implement automatic pagination with async iterators 4. Hardcoded Credentials - Use environment variables or config files 5. Missing Idempotency - Add idempotency keys to prevent duplicate operations 6. Ignoring Rate Limits - Respect Retry-After header on 429 responses 7. Breaking Changes - Use SemVer, deprecate before removing

Integration with Other Skills

• api-design-principles: API design complements SDK design (error codes → error classes)
• building-clis: CLIs wrap SDKs for command-line access
• testing-strategies: Test SDKs with mocked HTTP, retry scenarios

Next Steps

Review language-specific examples for implementation details. Study references for deep dives on specific patterns. Examine best-in-class SDKs (Stripe, AWS, OpenAI) for inspiration.

SDK Architecture Patterns

Comprehensive guide to organizing SDK code for maintainability, discoverability, and developer experience.

Table of Contents

1. Resource-Based Architecture 2. Command-Based Architecture 3. Hybrid Approaches 4. Client Organization 5. Decision Framework

Resource-Based Architecture

Overview

Resource-based SDKs organize methods around API resources (users, payments, customers). Each resource is a class or object with CRUD methods.

Example (Stripe-style):

const stripe = new Stripe('sk_test_...')

// Resource-based organization
const customer = await stripe.customers.create({ email: 'user@example.com' })
const charge = await stripe.charges.create({ amount: 1000, customer: customer.id })
const invoice = await stripe.invoices.retrieve('inv_123')

Structure

Client
├─ customers (CustomersResource)
│   ├─ create(params)
│   ├─ retrieve(id)
│   ├─ update(id, params)
│   ├─ delete(id)
│   └─ list(params)
├─ charges (ChargesResource)
│   ├─ create(params)
│   └─ refund(id)
└─ invoices (InvoicesResource)
    ├─ retrieve(id)
    └─ finalize(id)

Implementation (TypeScript)

class StripeClient {
  private apiKey: string
  private baseURL: string

  constructor(apiKey: string) {
    this.apiKey = apiKey
    this.baseURL = 'https://api.stripe.com/v1'
  }

  // Lazy-loaded resources
  get customers() {
    return new CustomersResource(this)
  }

  get charges() {
    return new ChargesResource(this)
  }

  // Core request method
  async request(method: string, path: string, params?: any) {
    // HTTP request implementation
  }
}

class CustomersResource {
  constructor(private client: StripeClient) {}

  async create(params: CreateCustomerParams) {
    return this.client.request('POST', '/customers', params)
  }

  async retrieve(id: string) {
    return this.client.request('GET', `/customers/${id}`)
  }

  async update(id: string, params: UpdateCustomerParams) {
    return this.client.request('PATCH', `/customers/${id}`, params)
  }

  async delete(id: string) {
    return this.client.request('DELETE', `/customers/${id}`)
  }

  async *list(params?: ListParams): AsyncGenerator<Customer> {
    // Pagination implementation
  }
}

Advantages

1. Intuitive: Matches API documentation and mental models 2. Discoverable: Autocomplete shows all available resources 3. Clear Namespacing: No method name conflicts (customers.create vs. charges.create) 4. Easy to Extend: Add new resources without changing existing code 5. Developer Experience: Users can easily find methods

Disadvantages

1. Bundle Size: All resources loaded even if unused 2. Tree-Shaking: Harder to eliminate dead code 3. Maintenance: More files and classes to maintain

When to Use

• Small-to-medium API surface (<100 methods)
• Developer experience is priority
• Bundle size is not critical (Node.js servers)
• API has clear resource boundaries (REST APIs)

---

Command-Based Architecture

Overview

Command-based SDKs (AWS SDK v3 pattern) separate client from commands. Each operation is a command object sent through the client.

Example (AWS SDK v3):

import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3'

const client = new S3Client({ region: 'us-east-1' })

// Command-based organization
const putCommand = new PutObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'content' })
await client.send(putCommand)

const getCommand = new GetObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt' })
const result = await client.send(getCommand)

Structure

Client (generic send method)
Commands (separate imports)
├─ PutObjectCommand
├─ GetObjectCommand
├─ DeleteObjectCommand
└─ ListObjectsCommand

Implementation (TypeScript)

// Client (generic)
class S3Client {
  private config: ClientConfig

  constructor(config: ClientConfig) {
    this.config = config
  }

  async send<Input, Output>(command: Command<Input, Output>): Promise<Output> {
    // Middleware pipeline
    const request = command.serialize(this.config)
    const response = await this.httpHandler.handle(request)
    return command.deserialize(response)
  }
}

// Command interface
interface Command<Input, Output> {
  serialize(config: ClientConfig): HttpRequest
  deserialize(response: HttpResponse): Output
}

// Concrete command
class PutObjectCommand implements Command<PutObjectInput, PutObjectOutput> {
  constructor(private input: PutObjectInput) {}

  serialize(config: ClientConfig): HttpRequest {
    return {
      method: 'PUT',
      path: `/${this.input.Bucket}/${this.input.Key}`,
      headers: { 'Content-Type': 'application/octet-stream' },
      body: this.input.Body
    }
  }

  deserialize(response: HttpResponse): PutObjectOutput {
    return {
      ETag: response.headers['etag'],
      VersionId: response.headers['x-amz-version-id']
    }
  }
}

// Usage
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'

const client = new S3Client({ region: 'us-east-1' })
const command = new PutObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt', Body: 'content' })
const result = await client.send(command)

Advantages

1. Tree-Shakeable: Import only needed commands 2. Smaller Bundles: Eliminate unused code (critical for browsers) 3. Modular: Each command is independent 4. Middleware: Easy to add cross-cutting concerns 5. Testable: Mock commands independently

Disadvantages

1. Verbose: Two steps (create command, send command) 2. Less Intuitive: Extra indirection 3. Discovery: Harder to find available operations 4. Boilerplate: More code to write

When to Use

• Large API surface (>100 methods)
• Bundle size is critical (browser SDKs)
• Modular architecture preferred
• Middleware/interceptors needed
• API surface changes frequently

---

Hybrid Approaches

Top-Level Convenience + Resources

Combine both patterns:

class APIClient {
  // Resource-based (full control)
  get users() {
    return new UsersResource(this)
  }

  // Top-level convenience methods
  async createUser(params: CreateUserParams) {
    return this.users.create(params)
  }

  async getUser(id: string) {
    return this.users.retrieve(id)
  }
}

// Usage (both work)
await client.createUser({ email: 'user@example.com' })  // Convenience
await client.users.create({ email: 'user@example.com' }) // Resource

Advantages:

• Quick common operations (top-level)
• Advanced use cases (resources)
• Backward compatibility

Disadvantages:

• Two ways to do the same thing
• Larger API surface

---

Client Organization

Configuration

interface ClientConfig {
  // Required
  apiKey: string

  // Optional with defaults
  baseURL?: string
  maxRetries?: number
  timeout?: number
  apiVersion?: string

  // Callbacks
  onTokenRefresh?: (token: string) => void
  onRequest?: (config: RequestConfig) => void
  onResponse?: (response: Response) => void
}

class APIClient {
  constructor(config: ClientConfig) {
    this.apiKey = config.apiKey
    this.baseURL = config.baseURL || 'https://api.example.com'
    this.maxRetries = config.maxRetries ?? 3
    this.timeout = config.timeout ?? 30000
  }
}

Core Request Method

All resource methods delegate to a central request method:

class APIClient {
  async request<T>(
    method: string,
    path: string,
    options?: {
      body?: any
      query?: Record<string, string>
      headers?: Record<string, string>
    }
  ): Promise<T> {
    // 1. Build URL
    const url = new URL(path, this.baseURL)
    if (options?.query) {
      Object.entries(options.query).forEach(([key, value]) => {
        url.searchParams.append(key, value)
      })
    }

    // 2. Build headers
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json',
      ...options?.headers
    }

    // 3. Make request with retry
    let attempt = 0
    while (attempt <= this.maxRetries) {
      try {
        const response = await fetch(url.toString(), {
          method,
          headers,
          body: options?.body ? JSON.stringify(options.body) : undefined,
          signal: AbortSignal.timeout(this.timeout)
        })

        if (!response.ok) {
          throw await this.handleErrorResponse(response)
        }

        return await response.json()
      } catch (error) {
        if (++attempt > this.maxRetries || !this.isRetryable(error)) {
          throw error
        }
        await this.sleep(this.calculateBackoff(attempt))
      }
    }

    throw new Error('Max retries exceeded')
  }

  private isRetryable(error: any): boolean {
    return (
      error.code === 'ECONNRESET' ||
      error.code === 'ETIMEDOUT' ||
      (error.status >= 500 && error.status < 600) ||
      error.status === 429
    )
  }

  private calculateBackoff(attempt: number): number {
    const baseDelay = 1000
    const maxDelay = 10000
    const exponential = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay)
    const jitter = Math.random() * 500
    return exponential + jitter
  }

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

Resource Classes

class UsersResource {
  constructor(private client: APIClient) {}

  async create(params: CreateUserParams): Promise<User> {
    return this.client.request<User>('POST', '/users', { body: params })
  }

  async retrieve(id: string): Promise<User> {
    return this.client.request<User>('GET', `/users/${id}`)
  }

  async update(id: string, params: UpdateUserParams): Promise<User> {
    return this.client.request<User>('PATCH', `/users/${id}`, { body: params })
  }

  async delete(id: string): Promise<void> {
    await this.client.request<void>('DELETE', `/users/${id}`)
  }

  async *list(params?: ListParams): AsyncGenerator<User> {
    let cursor: string | undefined = undefined

    while (true) {
      const response = await this.client.request<ListUsersResponse>('GET', '/users', {
        query: {
          limit: String(params?.limit || 100),
          ...(cursor ? { cursor } : {})
        }
      })

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

      if (!response.has_more) break
      cursor = response.next_cursor
    }
  }
}

---

Decision Framework

Choose Resource-Based If:

• API has <100 methods
• Clear resource boundaries (REST API)
• Developer experience is priority
• Target is Node.js servers (bundle size not critical)
• Team is familiar with Stripe/Twilio SDKs

Choose Command-Based If:

• API has >100 methods
• Bundle size is critical (browser SDKs)
• Modular architecture preferred
• Need tree-shaking for performance
• Middleware/plugin system required

Choose Hybrid If:

• Want both convenience and flexibility
• Backward compatibility with existing API
• Different user personas (beginners vs. advanced)
• Gradual migration from one pattern to another

Language-Specific Considerations

TypeScript/JavaScript:

• Both patterns work well
• Resource-based more common for web APIs
• Command-based for large APIs (AWS)

Python:

• Resource-based is pythonic
• Use properties for lazy-loaded resources
• Context managers for client lifecycle

Go:

• Resource-based with interfaces
• Use exported functions for package-level API
• Context.Context required for all operations

---

Real-World Examples

Resource-Based:

• Stripe (Node, Python, Go)
• Twilio
• SendGrid
• Most SaaS APIs

Command-Based:

• AWS SDK v3 (JavaScript)
• AWS SDK v2 (Go)
• Google Cloud Client Libraries

Hybrid:

• GitHub API (Octokit)
• OpenAI (convenience + resource methods)

Authentication Patterns for SDKs

Comprehensive guide to handling authentication in client libraries, from simple API keys to complex OAuth flows.

Table of Contents

1. API Key Authentication 2. OAuth 2.0 Token Management 3. Bearer Token Injection 4. JWT Authentication 5. Credential Storage 6. Multi-Tenant Authentication

API Key Authentication

Pattern 1: API Key in Constructor

Most common pattern for service-to-service authentication.

TypeScript:

class APIClient {
  private apiKey: string

  constructor(apiKey: string) {
    this.apiKey = apiKey
  }

  async request(method: string, path: string, options?: any) {
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json',
      ...options?.headers
    }

    const response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers,
      body: options?.body ? JSON.stringify(options.body) : undefined
    })

    return response.json()
  }
}

// Usage
const client = new APIClient(process.env.API_KEY!)

Python:

class APIClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://api.example.com"

    def request(self, method: str, path: str, body=None):
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

        response = requests.request(
            method=method,
            url=f"{self.base_url}{path}",
            json=body,
            headers=headers
        )

        return response.json()

# Usage
client = APIClient(os.environ['API_KEY'])

Go:

type Client struct {
    apiKey  string
    baseURL string
}

func New(apiKey string) *Client {
    return &Client{
        apiKey:  apiKey,
        baseURL: "https://api.example.com",
    }
}

func (c *Client) request(ctx context.Context, method, path string, body interface{}) (interface{}, error) {
    req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, nil)
    if err != nil {
        return nil, err
    }

    req.Header.Set("Authorization", "Bearer "+c.apiKey)
    req.Header.Set("Content-Type", "application/json")

    // Execute request
}

// Usage
client := apiclient.New(os.Getenv("API_KEY"))

Pattern 2: API Key in Header vs. Query Parameter

Header-Based (Recommended):

headers: {
  'Authorization': `Bearer ${apiKey}`
}

Query Parameter (Avoid if possible):

const url = `${baseURL}${path}?api_key=${apiKey}`

Rationale:

• Headers are more secure (not logged by proxies)
• Headers don't appear in browser history
• Query parameters may be cached

---

OAuth 2.0 Token Management

Pattern 1: Automatic Token Refresh

TypeScript:

interface OAuthConfig {
  clientId: string
  clientSecret: string
  accessToken: string
  refreshToken: string
  expiresAt: Date
  onTokenRefresh?: (tokens: TokenResponse) => void
}

interface TokenResponse {
  access_token: string
  refresh_token: string
  expires_in: number
}

class OAuthClient {
  private config: OAuthConfig

  constructor(config: OAuthConfig) {
    this.config = config
  }

  async request(method: string, path: string, options?: any) {
    // Check if token is expired
    if (this.isTokenExpired()) {
      await this.refreshAccessToken()
    }

    const headers = {
      'Authorization': `Bearer ${this.config.accessToken}`,
      'Content-Type': 'application/json',
      ...options?.headers
    }

    const response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers,
      body: options?.body ? JSON.stringify(options.body) : undefined
    })

    // Handle 401 (token expired during request)
    if (response.status === 401) {
      await this.refreshAccessToken()
      // Retry request
      return this.request(method, path, options)
    }

    return response.json()
  }

  private isTokenExpired(): boolean {
    // Refresh 5 minutes before actual expiry
    const bufferTime = 5 * 60 * 1000 // 5 minutes
    return Date.now() >= this.config.expiresAt.getTime() - bufferTime
  }

  private async refreshAccessToken(): Promise<void> {
    const response = await fetch('https://api.example.com/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: this.config.refreshToken,
        client_id: this.config.clientId,
        client_secret: this.config.clientSecret
      })
    })

    const tokens: TokenResponse = await response.json()

    // Update config
    this.config.accessToken = tokens.access_token
    this.config.refreshToken = tokens.refresh_token
    this.config.expiresAt = new Date(Date.now() + tokens.expires_in * 1000)

    // Notify callback
    if (this.config.onTokenRefresh) {
      this.config.onTokenRefresh(tokens)
    }
  }
}

// Usage
const client = new OAuthClient({
  clientId: 'client_id',
  clientSecret: 'client_secret',
  accessToken: 'current_access_token',
  refreshToken: 'refresh_token',
  expiresAt: new Date('2025-12-31'),
  onTokenRefresh: (tokens) => {
    // Save new tokens to database
    saveTokens(tokens)
  }
})

// SDK automatically refreshes token
const user = await client.users.create({ email: 'user@example.com' })

Python:

from datetime import datetime, timedelta
from typing import Callable, Optional

class OAuthClient:
    def __init__(
        self,
        client_id: str,
        client_secret: str,
        access_token: str,
        refresh_token: str,
        expires_at: datetime,
        on_token_refresh: Optional[Callable[[dict], None]] = None
    ):
        self.client_id = client_id
        self.client_secret = client_secret
        self.access_token = access_token
        self.refresh_token = refresh_token
        self.expires_at = expires_at
        self.on_token_refresh = on_token_refresh

    def request(self, method: str, path: str, body=None):
        # Check if token is expired
        if self._is_token_expired():
            self._refresh_access_token()

        headers = {
            "Authorization": f"Bearer {self.access_token}",
            "Content-Type": "application/json"
        }

        response = requests.request(
            method=method,
            url=f"{self.base_url}{path}",
            json=body,
            headers=headers
        )

        # Handle 401
        if response.status_code == 401:
            self._refresh_access_token()
            return self.request(method, path, body)

        return response.json()

    def _is_token_expired(self) -> bool:
        # Refresh 5 minutes before expiry
        buffer = timedelta(minutes=5)
        return datetime.now() >= self.expires_at - buffer

    def _refresh_access_token(self):
        response = requests.post(
            "https://api.example.com/oauth/token",
            data={
                "grant_type": "refresh_token",
                "refresh_token": self.refresh_token,
                "client_id": self.client_id,
                "client_secret": self.client_secret
            }
        )

        tokens = response.json()

        # Update tokens
        self.access_token = tokens['access_token']
        self.refresh_token = tokens['refresh_token']
        self.expires_at = datetime.now() + timedelta(seconds=tokens['expires_in'])

        # Notify callback
        if self.on_token_refresh:
            self.on_token_refresh(tokens)

---

Bearer Token Injection

Pattern: Per-Request Token

For multi-tenant applications where each request uses a different user token.

TypeScript:

class APIClient {
  private baseURL: string

  constructor(baseURL: string) {
    this.baseURL = baseURL
  }

  async request(
    method: string,
    path: string,
    options?: {
      body?: any
      headers?: Record<string, string>
      token?: string // Per-request token
    }
  ) {
    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      ...options?.headers
    }

    // Add token if provided
    if (options?.token) {
      headers['Authorization'] = `Bearer ${options.token}`
    }

    const response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers,
      body: options?.body ? JSON.stringify(options.body) : undefined
    })

    return response.json()
  }
}

// Usage in multi-tenant app
const client = new APIClient('https://api.example.com')

// Request 1 (user A's token)
const userAData = await client.request('GET', '/users/me', {
  token: userAToken
})

// Request 2 (user B's token)
const userBData = await client.request('GET', '/users/me', {
  token: userBToken
})

---

JWT Authentication

Pattern: JWT with Automatic Refresh

TypeScript:

interface JWTConfig {
  getAccessToken: () => string
  getRefreshToken: () => string
  onTokenRefresh: (tokens: { accessToken: string; refreshToken: string }) => void
}

class JWTClient {
  private config: JWTConfig

  constructor(config: JWTConfig) {
    this.config = config
  }

  async request(method: string, path: string, options?: any) {
    const accessToken = this.config.getAccessToken()

    const headers = {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
      ...options?.headers
    }

    let response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers,
      body: options?.body ? JSON.stringify(options.body) : undefined
    })

    // Handle 401 (expired token)
    if (response.status === 401) {
      const newTokens = await this.refreshToken()
      this.config.onTokenRefresh(newTokens)

      // Retry with new token
      headers['Authorization'] = `Bearer ${newTokens.accessToken}`
      response = await fetch(`${this.baseURL}${path}`, {
        method,
        headers,
        body: options?.body ? JSON.stringify(options.body) : undefined
      })
    }

    return response.json()
  }

  private async refreshToken(): Promise<{ accessToken: string; refreshToken: string }> {
    const refreshToken = this.config.getRefreshToken()

    const response = await fetch(`${this.baseURL}/auth/refresh`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refreshToken })
    })

    const { accessToken, refreshToken: newRefreshToken } = await response.json()

    return {
      accessToken,
      refreshToken: newRefreshToken
    }
  }
}

// Usage with local storage
const client = new JWTClient({
  getAccessToken: () => localStorage.getItem('accessToken') || '',
  getRefreshToken: () => localStorage.getItem('refreshToken') || '',
  onTokenRefresh: (tokens) => {
    localStorage.setItem('accessToken', tokens.accessToken)
    localStorage.setItem('refreshToken', tokens.refreshToken)
  }
})

---

Credential Storage

Environment Variables (Recommended)

TypeScript (Node.js):

const client = new APIClient({
  apiKey: process.env.API_KEY!
})

Python:

import os

client = APIClient(api_key=os.environ['API_KEY'])

Go:

import "os"

client := apiclient.New(os.Getenv("API_KEY"))

Configuration Files

TypeScript (dotenv):

import dotenv from 'dotenv'
dotenv.config()

const client = new APIClient({
  apiKey: process.env.API_KEY!
})

.env file:

API_KEY=sk_test_1234567890abcdef
API_BASE_URL=https://api.example.com

Credential Providers (AWS SDK Pattern)

interface CredentialProvider {
  getCredentials(): Promise<Credentials>
}

class EnvironmentCredentialProvider implements CredentialProvider {
  async getCredentials(): Promise<Credentials> {
    return {
      apiKey: process.env.API_KEY || ''
    }
  }
}

class FileCredentialProvider implements CredentialProvider {
  constructor(private filePath: string) {}

  async getCredentials(): Promise<Credentials> {
    const config = await fs.readFile(this.filePath, 'utf-8')
    const parsed = JSON.parse(config)
    return {
      apiKey: parsed.apiKey
    }
  }
}

class APIClient {
  private credentialProvider: CredentialProvider

  constructor(credentialProvider: CredentialProvider) {
    this.credentialProvider = credentialProvider
  }

  async request(method: string, path: string, options?: any) {
    const credentials = await this.credentialProvider.getCredentials()

    const headers = {
      'Authorization': `Bearer ${credentials.apiKey}`,
      ...options?.headers
    }

    // Make request
  }
}

// Usage
const client = new APIClient(new EnvironmentCredentialProvider())
// or
const client = new APIClient(new FileCredentialProvider('~/.config/api/credentials.json'))

---

Multi-Tenant Authentication

Pattern: Token Manager

For applications managing multiple API clients:

class TokenManager {
  private tokens: Map<string, string> = new Map()

  setToken(tenantId: string, token: string) {
    this.tokens.set(tenantId, token)
  }

  getToken(tenantId: string): string | undefined {
    return this.tokens.get(tenantId)
  }
}

class MultiTenantClient {
  private tokenManager: TokenManager

  constructor(tokenManager: TokenManager) {
    this.tokenManager = tokenManager
  }

  async request(
    tenantId: string,
    method: string,
    path: string,
    options?: any
  ) {
    const token = this.tokenManager.getToken(tenantId)

    if (!token) {
      throw new Error(`No token for tenant: ${tenantId}`)
    }

    const headers = {
      'Authorization': `Bearer ${token}`,
      ...options?.headers
    }

    const response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers,
      body: options?.body ? JSON.stringify(options.body) : undefined
    })

    return response.json()
  }
}

// Usage
const tokenManager = new TokenManager()
tokenManager.setToken('tenant-a', 'token-a')
tokenManager.setToken('tenant-b', 'token-b')

const client = new MultiTenantClient(tokenManager)

// Request for tenant A
await client.request('tenant-a', 'GET', '/users')

// Request for tenant B
await client.request('tenant-b', 'GET', '/users')

---

Best Practices

Security

1. Never Hardcode Credentials

   // ❌ Bad
   const client = new APIClient({ apiKey: 'sk_test_1234' })

   // ✅ Good
   const client = new APIClient({ apiKey: process.env.API_KEY })

2. Use HTTPS Only

   if (!this.baseURL.startsWith('https://')) {
     throw new Error('API base URL must use HTTPS')
   }

3. Don't Log Credentials

   // ❌ Bad
   console.log('Making request with API key:', apiKey)

   // ✅ Good
   console.log('Making request to:', path)

4. Rotate Credentials

• Support credential rotation without downtime
• Accept both old and new credentials during rotation period

Error Handling

class AuthenticationError extends Error {
  constructor(message: string, public requestId: string) {
    super(message)
    this.name = 'AuthenticationError'
  }
}

if (response.status === 401) {
  throw new AuthenticationError(
    'Invalid API key or expired token',
    response.headers.get('x-request-id') || 'unknown'
  )
}

Token Storage

Browser (Web Storage API):

// Use sessionStorage for sensitive tokens (cleared on tab close)
sessionStorage.setItem('accessToken', token)

// Use localStorage for less sensitive tokens (persistent)
localStorage.setItem('refreshToken', token)

Node.js (Keychain):

import keytar from 'keytar'

// Store securely in OS keychain
await keytar.setPassword('my-app', 'api-key', apiKey)

// Retrieve
const apiKey = await keytar.getPassword('my-app', 'api-key')

---

Language-Specific Patterns

Python Context Managers

class APIClient:
    def __enter__(self):
        # Initialize client
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        # Cleanup (revoke tokens, close connections)
        self.close()

# Usage
with APIClient(api_key=os.environ['API_KEY']) as client:
    user = client.users.create(email='user@example.com')
# Token automatically cleaned up

Go Context for Auth

type authKey struct{}

func WithToken(ctx context.Context, token string) context.Context {
    return context.WithValue(ctx, authKey{}, token)
}

func (c *Client) request(ctx context.Context, method, path string) (interface{}, error) {
    token, ok := ctx.Value(authKey{}).(string)
    if !ok {
        return nil, errors.New("no auth token in context")
    }

    req.Header.Set("Authorization", "Bearer "+token)
    // Make request
}

// Usage
ctx := context.Background()
ctx = apiclient.WithToken(ctx, "api_key")
user, err := client.Users().Create(ctx, req)

Error Handling in SDKs

Guide to creating typed error hierarchies, error metadata, and user-friendly error messages.

Table of Contents

1. Typed Error Hierarchy 2. Python Error Hierarchy 3. Go Error Types 4. Error Handling Patterns 5. User-Friendly Error Messages 6. Debugging Support

Typed Error Hierarchy

Base Error Class

class APIError extends Error {
  constructor(
    message: string,
    public status: number,
    public code: string,
    public requestId: string,
    public headers?: Record<string, string>
  ) {
    super(message)
    this.name = 'APIError'
    Object.setPrototypeOf(this, APIError.prototype)
  }

  toJSON() {
    return {
      name: this.name,
      message: this.message,
      status: this.status,
      code: this.code,
      requestId: this.requestId
    }
  }
}

Specific Error Types

class RateLimitError extends APIError {
  constructor(message: string, requestId: string, headers: Record<string, string>) {
    super(message, 429, 'rate_limit_error', requestId, headers)
    this.name = 'RateLimitError'
  }

  get retryAfter(): number {
    return parseInt(this.headers?.['retry-after'] || '60')
  }
}

class AuthenticationError extends APIError {
  constructor(message: string, requestId: string) {
    super(message, 401, 'authentication_error', requestId)
    this.name = 'AuthenticationError'
  }
}

class InvalidRequestError extends APIError {
  constructor(
    message: string,
    requestId: string,
    public param?: string,
    public validationErrors?: Array<{field: string; message: string}>
  ) {
    super(message, 400, 'invalid_request_error', requestId)
    this.name = 'InvalidRequestError'
  }
}

class NotFoundError extends APIError {
  constructor(message: string, requestId: string, public resourceType?: string) {
    super(message, 404, 'not_found', requestId)
    this.name = 'NotFoundError'
  }
}

class PermissionError extends APIError {
  constructor(message: string, requestId: string) {
    super(message, 403, 'permission_denied', requestId)
    this.name = 'PermissionError'
  }
}

class ServerError extends APIError {
  constructor(message: string, status: number, requestId: string) {
    super(message, status, 'server_error', requestId)
    this.name = 'ServerError'
  }
}

Error Factory

function createErrorFromResponse(response: Response, requestId: string): APIError {
  const status = response.status
  const errorData = response.data || {}

  switch (status) {
    case 400:
      return new InvalidRequestError(
        errorData.message || 'Invalid request',
        requestId,
        errorData.param,
        errorData.errors
      )
    case 401:
      return new AuthenticationError(
        errorData.message || 'Authentication failed',
        requestId
      )
    case 403:
      return new PermissionError(
        errorData.message || 'Permission denied',
        requestId
      )
    case 404:
      return new NotFoundError(
        errorData.message || 'Resource not found',
        requestId,
        errorData.resource
      )
    case 429:
      return new RateLimitError(
        errorData.message || 'Rate limit exceeded',
        requestId,
        response.headers
      )
    case 500:
    case 502:
    case 503:
    case 504:
      return new ServerError(
        errorData.message || 'Server error',
        status,
        requestId
      )
    default:
      return new APIError(
        errorData.message || `HTTP ${status}`,
        status,
        errorData.code || 'unknown_error',
        requestId
      )
  }
}

Python Error Hierarchy

class APIError(Exception):
    def __init__(self, message: str, status: int, code: str, request_id: str):
        super().__init__(message)
        self.message = message
        self.status = status
        self.code = code
        self.request_id = request_id

    def __str__(self):
        return f"{self.name}: {self.message} (status={self.status}, request_id={self.request_id})"

    @property
    def name(self):
        return self.__class__.__name__

class RateLimitError(APIError):
    def __init__(self, message: str, request_id: str, retry_after: int):
        super().__init__(message, 429, 'rate_limit_error', request_id)
        self.retry_after = retry_after

class AuthenticationError(APIError):
    def __init__(self, message: str, request_id: str):
        super().__init__(message, 401, 'authentication_error', request_id)

class InvalidRequestError(APIError):
    def __init__(self, message: str, request_id: str, param: str = None):
        super().__init__(message, 400, 'invalid_request_error', request_id)
        self.param = param

Go Error Types

type APIError struct {
    Message   string
    Status    int
    Code      string
    RequestID string
}

func (e *APIError) Error() string {
    return fmt.Sprintf("%s: %s (status=%d, request_id=%s)",
        e.Code, e.Message, e.Status, e.RequestID)
}

type RateLimitError struct {
    APIError
    RetryAfter int
}

type AuthenticationError struct {
    APIError
}

type InvalidRequestError struct {
    APIError
    Param string
}

Error Handling Patterns

Try-Catch with Type Guards

try {
  const user = await client.users.create({ email: 'invalid' })
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`)
    await sleep(error.retryAfter * 1000)
    // Retry request
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key. Check your credentials.')
  } else if (error instanceof InvalidRequestError) {
    console.error(`Invalid parameter: ${error.param}`)
    if (error.validationErrors) {
      error.validationErrors.forEach(err => {
        console.error(`  - ${err.field}: ${err.message}`)
      })
    }
  } else if (error instanceof NotFoundError) {
    console.error(`${error.resourceType || 'Resource'} not found`)
  } else if (error instanceof PermissionError) {
    console.error('Insufficient permissions')
  } else if (error instanceof ServerError) {
    console.error('Server error. Please try again later.')
  } else {
    // Unknown error
    console.error('Unexpected error:', error)
    throw error
  }
}

Python Exception Handling

try:
    user = client.users.create(email='invalid')
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
    time.sleep(e.retry_after)
except AuthenticationError:
    print("Invalid API key")
except InvalidRequestError as e:
    print(f"Invalid parameter: {e.param}")
except APIError as e:
    print(f"API Error: {e.message} ({e.code})")

User-Friendly Error Messages

Include Context

class InvalidRequestError extends APIError {
  constructor(
    message: string,
    requestId: string,
    public param?: string,
    public expected?: string
  ) {
    // Enhance message with context
    const fullMessage = param
      ? `Invalid ${param}: ${message}${expected ? `. Expected: ${expected}` : ''}`
      : message

    super(fullMessage, 400, 'invalid_request_error', requestId)
  }
}

// Usage
throw new InvalidRequestError(
  'must be a valid email address',
  requestId,
  'email',
  'format: user@example.com'
)
// Error: "Invalid email: must be a valid email address. Expected: format: user@example.com"

Link to Documentation

class APIError extends Error {
  constructor(
    message: string,
    public status: number,
    public code: string,
    public requestId: string,
    public docUrl?: string
  ) {
    super(message)
    this.docUrl = docUrl || `https://docs.example.com/errors/${code}`
  }

  toString(): string {
    return `${this.message}\n\nFor more information: ${this.docUrl}\nRequest ID: ${this.requestId}`
  }
}

Actionable Guidance

throw new AuthenticationError(
  'API key is invalid. Please check that you are using the correct API key from your dashboard (https://dashboard.example.com/api-keys).',
  requestId
)

throw new RateLimitError(
  'You have exceeded the rate limit. Please wait 60 seconds before retrying, or upgrade your plan for higher limits (https://example.com/pricing).',
  requestId,
  60
)

Debugging Support

Request ID in All Errors

async request(method: string, path: string, options?: any) {
  const response = await fetch(...)

  const requestId = response.headers.get('x-request-id') || randomUUID()

  if (!response.ok) {
    throw createErrorFromResponse(response, requestId)
  }
}

Stack Traces

class APIError extends Error {
  constructor(...) {
    super(message)
    // Capture stack trace
    Error.captureStackTrace(this, this.constructor)
  }
}

Logging Integration

class APIClient {
  async request(method: string, path: string, options?: any) {
    try {
      const response = await fetch(...)
      return response.json()
    } catch (error) {
      // Log error details
      console.error('API request failed:', {
        method,
        path,
        error: error instanceof APIError ? error.toJSON() : error,
        timestamp: new Date().toISOString()
      })

      throw error
    }
  }
}

Pagination Patterns

Guide to implementing cursor-based and offset-based pagination with async iterators.

Table of Contents

1. Async Iterator Pattern 2. Manual Pagination 3. Go Pagination with Channels

Async Iterator Pattern (Recommended)

TypeScript Implementation

class UsersResource {
  async *list(options?: { limit?: number }): AsyncGenerator<User> {
    let cursor: string | undefined = undefined

    while (true) {
      const response = await this.client.request<ListResponse>('GET', '/users', {
        query: {
          limit: String(options?.limit || 100),
          ...(cursor ? { cursor } : {})
        }
      })

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

      if (!response.has_more) break
      cursor = response.next_cursor
    }
  }
}

// Usage
for await (const user of client.users.list({ limit: 50 })) {
  console.log(user.id, user.email)
}

Python Implementation

from typing import AsyncGenerator, Generator, Optional

class UsersResource:
    # Sync iterator
    def list(self, limit: int = 100) -> Generator[User, None, None]:
        cursor = None

        while True:
            response = self._client.request('GET', '/users', query={
                'limit': limit,
                **({"cursor': cursor} if cursor else {})
            })

            for user in response['data']:
                yield user

            if not response.get('has_more'):
                break
            cursor = response.get('next_cursor')

    # Async iterator
    async def list_async(self, limit: int = 100) -> AsyncGenerator[User, None]:
        cursor = None

        while True:
            response = await self._client.request('GET', '/users', query={
                'limit': limit,
                **({"cursor': cursor} if cursor else {})
            })

            for user in response['data']:
                yield user

            if not response.get('has_more'):
                break
            cursor = response.get('next_cursor')

# Usage
for user in client.users.list(limit=50):
    print(user.id, user.email)

# Async
async for user in client.users.list_async(limit=50):
    print(user.id, user.email)

Manual Pagination

Cursor-Based

interface ListResponse<T> {
  data: T[]
  has_more: boolean
  next_cursor?: string
}

async function paginateManually() {
  let cursor: string | undefined = undefined
  let hasMore = true

  while (hasMore) {
    const response = await client.users.list({ limit: 100, cursor })

    for (const user of response.data) {
      console.log(user.id)
    }

    cursor = response.next_cursor
    hasMore = response.has_more
  }
}

Offset-Based

async function paginateWithOffset() {
  let page = 1
  let totalPages = Infinity

  while (page <= totalPages) {
    const response = await client.users.list({ page, perPage: 100 })

    for (const user of response.data) {
      console.log(user.id)
    }

    totalPages = response.total_pages
    page++
  }
}

Go Pagination with Channels

func (r *UsersResource) List(ctx context.Context, limit int) (<-chan User, <-chan error) {
    userCh := make(chan User)
    errCh := make(chan error, 1)

    go func() {
        defer close(userCh)
        defer close(errCh)

        cursor := ""
        for {
            query := map[string]string{"limit": strconv.Itoa(limit)}
            if cursor != "" {
                query["cursor"] = cursor
            }

            response, err := r.client.request(ctx, "GET", "/users", query)
            if err != nil {
                errCh <- err
                return
            }

            for _, user := range response.Data {
                select {
                case <-ctx.Done():
                    errCh <- ctx.Err()
                    return
                case userCh <- user:
                }
            }

            if !response.HasMore {
                break
            }
            cursor = response.NextCursor
        }
    }()

    return userCh, errCh
}

Retry and Backoff Strategies

Comprehensive guide to implementing retry logic with exponential backoff, jitter, and rate limit handling.

Table of Contents

1. Exponential Backoff 2. Jitter Strategies 3. Rate Limit Handling 4. Retry Decision Logic 5. Idempotency Keys

Exponential Backoff

Algorithm

delay = min(base_delay * (2 ^ attempt), max_delay) + jitter

Example progression:

• Attempt 1: 1s + jitter
• Attempt 2: 2s + jitter
• Attempt 3: 4s + jitter
• Attempt 4: 8s + jitter
• Attempt 5: 10s + jitter (capped at max_delay)

TypeScript Implementation

interface RetryOptions {
  maxRetries: number
  baseDelay: number // milliseconds
  maxDelay: number  // milliseconds
}

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  options: RetryOptions = {
    maxRetries: 3,
    baseDelay: 1000,
    maxDelay: 10000
  }
): Promise<T> {
  let attempt = 0

  while (attempt <= options.maxRetries) {
    try {
      return await fn()
    } catch (error) {
      attempt++

      if (attempt > options.maxRetries || !isRetryable(error)) {
        throw error
      }

      const delay = calculateBackoff(attempt, options)
      console.log(`Retry attempt ${attempt} after ${delay}ms`)
      await sleep(delay)
    }
  }

  throw new Error('Max retries exceeded')
}

function calculateBackoff(attempt: number, options: RetryOptions): number {
  const exponential = Math.min(
    options.baseDelay * Math.pow(2, attempt - 1),
    options.maxDelay
  )
  const jitter = Math.random() * 500 // 0-500ms
  return exponential + jitter
}

function isRetryable(error: any): boolean {
  return (
    error.code === 'ECONNRESET' ||
    error.code === 'ETIMEDOUT' ||
    (error.status >= 500 && error.status < 600) ||
    error.status === 429
  )
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms))
}

Python Implementation

import time
import random
from typing import TypeVar, Callable, Any

T = TypeVar('T')

def retry_with_backoff(
    fn: Callable[[], T],
    max_retries: int = 3,
    base_delay: float = 1.0,
    max_delay: float = 10.0
) -> T:
    attempt = 0

    while attempt <= max_retries:
        try:
            return fn()
        except Exception as error:
            attempt += 1

            if attempt > max_retries or not is_retryable(error):
                raise

            delay = calculate_backoff(attempt, base_delay, max_delay)
            print(f"Retry attempt {attempt} after {delay:.2f}s")
            time.sleep(delay)

    raise Exception("Max retries exceeded")

def calculate_backoff(attempt: int, base_delay: float, max_delay: float) -> float:
    exponential = min(base_delay * (2 ** (attempt - 1)), max_delay)
    jitter = random.random() * 0.5  # 0-0.5 seconds
    return exponential + jitter

def is_retryable(error: Exception) -> bool:
    if hasattr(error, 'status'):
        return error.status >= 500 or error.status == 429
    return False

Go Implementation

func retryWithBackoff[T any](
    fn func() (T, error),
    maxRetries int,
    baseDelay time.Duration,
    maxDelay time.Duration,
) (T, error) {
    var result T
    var lastErr error

    for attempt := 0; attempt <= maxRetries; attempt++ {
        result, err := fn()
        if err == nil {
            return result, nil
        }

        lastErr = err

        if !isRetryable(err) || attempt >= maxRetries {
            break
        }

        delay := calculateBackoff(attempt+1, baseDelay, maxDelay)
        fmt.Printf("Retry attempt %d after %v\n", attempt+1, delay)
        time.Sleep(delay)
    }

    return result, lastErr
}

func calculateBackoff(attempt int, baseDelay, maxDelay time.Duration) time.Duration {
    exponential := time.Duration(math.Min(
        float64(baseDelay)*math.Pow(2, float64(attempt-1)),
        float64(maxDelay),
    ))

    jitter := time.Duration(rand.Intn(500)) * time.Millisecond
    return exponential + jitter
}

Jitter Strategies

Full Jitter

Random delay between 0 and exponential backoff:

function calculateFullJitter(attempt: number, baseDelay: number, maxDelay: number): number {
  const exponential = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay)
  return Math.random() * exponential
}

Benefits:

• Maximum spread across time
• Best for preventing thundering herd
• Used by AWS SDK

Equal Jitter

Half exponential + half random:

function calculateEqualJitter(attempt: number, baseDelay: number, maxDelay: number): number {
  const exponential = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay)
  return exponential / 2 + Math.random() * (exponential / 2)
}

Benefits:

• Balance between predictability and spread
• Shorter average wait time than full jitter

Decorrelated Jitter

Each delay based on previous delay:

function calculateDecorrelatedJitter(
  previousDelay: number,
  baseDelay: number,
  maxDelay: number
): number {
  return Math.min(
    maxDelay,
    Math.random() * (previousDelay * 3 - baseDelay) + baseDelay
  )
}

Rate Limit Handling

Respect Retry-After Header

async function handleRateLimit(error: RateLimitError): Promise<void> {
  // Check for Retry-After header
  const retryAfter = error.retryAfter || 60

  console.log(`Rate limited. Retrying after ${retryAfter}s`)
  await sleep(retryAfter * 1000)
}

// In request method
if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get('retry-after') || '60')

  throw new RateLimitError(
    'Rate limit exceeded',
    response.headers.get('x-request-id') || 'unknown',
    retryAfter
  )
}

Rate Limit Budget Tracking

class RateLimiter {
  private remaining: number = 0
  private resetAt: Date = new Date()

  updateFromHeaders(headers: Headers) {
    const remaining = headers.get('x-ratelimit-remaining')
    const reset = headers.get('x-ratelimit-reset')

    if (remaining) {
      this.remaining = parseInt(remaining)
    }

    if (reset) {
      this.resetAt = new Date(parseInt(reset) * 1000)
    }
  }

  async waitIfNeeded(): Promise<void> {
    if (this.remaining <= 0) {
      const now = Date.now()
      const resetTime = this.resetAt.getTime()

      if (now < resetTime) {
        const waitMs = resetTime - now
        console.log(`Rate limit budget exhausted. Waiting ${waitMs}ms`)
        await sleep(waitMs)
      }
    }
  }
}

// Usage in client
class APIClient {
  private rateLimiter = new RateLimiter()

  async request(method: string, path: string, options?: any) {
    // Wait if rate limit budget exhausted
    await this.rateLimiter.waitIfNeeded()

    const response = await fetch(...)

    // Update rate limit tracking
    this.rateLimiter.updateFromHeaders(response.headers)

    return response.json()
  }
}

Retry Decision Logic

Retryable Errors

function isRetryable(error: any): boolean {
  // Network errors
  if (error.code === 'ECONNRESET') return true
  if (error.code === 'ETIMEDOUT') return true
  if (error.code === 'ECONNREFUSED') return true
  if (error.code === 'ENOTFOUND') return true

  // HTTP status codes
  if (!error.status) return false

  // 5xx server errors (retryable)
  if (error.status >= 500 && error.status < 600) return true

  // 429 rate limit (retryable)
  if (error.status === 429) return true

  // 408 request timeout (retryable)
  if (error.status === 408) return true

  // All other errors (not retryable)
  return false
}

Non-Retryable Errors

function isNonRetryable(error: any): boolean {
  if (!error.status) return false

  // 4xx client errors (except 408, 429)
  const nonRetryableStatuses = [400, 401, 403, 404, 405, 409, 410, 422]
  return nonRetryableStatuses.includes(error.status)
}

Idempotency Keys

Generate Idempotency Keys

import { randomUUID } from 'crypto'

class APIClient {
  async request(
    method: string,
    path: string,
    options?: {
      body?: any
      idempotencyKey?: string
    }
  ) {
    const headers: Record<string, string> = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json'
    }

    // Add idempotency key for mutating operations
    if (['POST', 'PATCH', 'PUT', 'DELETE'].includes(method.toUpperCase())) {
      headers['Idempotency-Key'] = options?.idempotencyKey || randomUUID()
    }

    // Make request with retry
    return retryWithBackoff(() => {
      return fetch(url, { method, headers, body: JSON.stringify(options?.body) })
    })
  }
}

// Usage: Custom idempotency key
await client.charges.create(
  { amount: 1000, currency: 'usd' },
  { idempotencyKey: 'charge_unique_123' }
)

Server-Side Idempotency

Server caches responses by idempotency key:

// Pseudo-code for server
const cache = new Map<string, Response>()

async function handleRequest(req: Request): Promise<Response> {
  const idempotencyKey = req.headers['idempotency-key']

  if (idempotencyKey && cache.has(idempotencyKey)) {
    // Return cached response
    return cache.get(idempotencyKey)!
  }

  const response = await processRequest(req)

  if (idempotencyKey) {
    // Cache response for 24 hours
    cache.set(idempotencyKey, response)
    setTimeout(() => cache.delete(idempotencyKey), 24 * 60 * 60 * 1000)
  }

  return response
}

Best Practices

Configuration

Allow users to configure retry behavior:

const client = new APIClient({
  apiKey: 'sk_test_...',
  retry: {
    maxRetries: 5,
    baseDelay: 1000,
    maxDelay: 30000,
    retryableStatuses: [429, 500, 502, 503, 504]
  }
})

Logging

Log retry attempts for debugging:

async function retryWithBackoff<T>(fn: () => Promise<T>, options: RetryOptions): Promise<T> {
  let attempt = 0

  while (attempt <= options.maxRetries) {
    try {
      const result = await fn()

      if (attempt > 0) {
        console.log(`Request succeeded after ${attempt} retries`)
      }

      return result
    } catch (error) {
      attempt++

      if (attempt > options.maxRetries || !isRetryable(error)) {
        if (attempt > 1) {
          console.error(`Request failed after ${attempt - 1} retries:`, error)
        }
        throw error
      }

      const delay = calculateBackoff(attempt, options)
      console.log(`Retry attempt ${attempt}/${options.maxRetries} after ${delay}ms (error: ${error.message})`)
      await sleep(delay)
    }
  }
}

Circuit Breaker

Stop retrying if service is down:

class CircuitBreaker {
  private failures = 0
  private lastFailure: Date | null = null
  private state: 'closed' | 'open' | 'half-open' = 'closed'

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      // Check if we should try again
      const now = Date.now()
      const lastFailureTime = this.lastFailure?.getTime() || 0
      const timeout = 60000 // 60 seconds

      if (now - lastFailureTime > timeout) {
        this.state = 'half-open'
      } else {
        throw new Error('Circuit breaker is open')
      }
    }

    try {
      const result = await fn()

      // Success - reset circuit
      this.failures = 0
      this.state = 'closed'

      return result
    } catch (error) {
      this.failures++
      this.lastFailure = new Date()

      // Open circuit after 5 failures
      if (this.failures >= 5) {
        this.state = 'open'
      }

      throw error
    }
  }
}

Testing SDK Code

Guide to unit testing, mocking HTTP requests, and integration testing for SDKs.

Table of Contents

1. Mocking HTTP Requests 2. Integration Tests

Mocking HTTP Requests

TypeScript (Vitest)

import { describe, it, expect, vi } from 'vitest'

describe('APIClient', () => {
  it('should create a user', async () => {
    // Mock fetch
    global.fetch = vi.fn().mockResolvedValue({
      ok: true,
      status: 200,
      json: async () => ({ id: '123', email: 'user@example.com' }),
      headers: new Headers({ 'x-request-id': 'req_123' })
    })

    const client = new APIClient({ apiKey: 'test_key' })
    const user = await client.users.create({ email: 'user@example.com' })

    expect(user.id).toBe('123')
    expect(user.email).toBe('user@example.com')
  })

  it('should retry on 500 error', async () => {
    const fetchMock = vi.fn()
      .mockResolvedValueOnce({ ok: false, status: 500 }) // First attempt fails
      .mockResolvedValueOnce({ // Second attempt succeeds
        ok: true,
        status: 200,
        json: async () => ({ id: '123' })
      })

    global.fetch = fetchMock

    const client = new APIClient({ apiKey: 'test_key', maxRetries: 3 })
    const user = await client.users.create({ email: 'user@example.com' })

    expect(fetchMock).toHaveBeenCalledTimes(2)
    expect(user.id).toBe('123')
  })
})

Python (pytest)

import pytest
from unittest.mock import Mock, patch

def test_create_user():
    with patch('requests.request') as mock_request:
        mock_request.return_value = Mock(
            status_code=200,
            json=lambda: {'id': '123', 'email': 'user@example.com'},
            headers={'x-request-id': 'req_123'}
        )

        client = APIClient(api_key='test_key')
        user = client.users.create(email='user@example.com')

        assert user['id'] == '123'
        assert user['email'] == 'user@example.com'

def test_retry_on_500():
    with patch('requests.request') as mock_request:
        # First call fails, second succeeds
        mock_request.side_effect = [
            Mock(status_code=500),
            Mock(status_code=200, json=lambda: {'id': '123'})
        ]

        client = APIClient(api_key='test_key', max_retries=3)
        user = client.users.create(email='user@example.com')

        assert mock_request.call_count == 2

Integration Tests

TypeScript

describe('APIClient Integration', () => {
  // Use real API in test environment
  const client = new APIClient({
    apiKey: process.env.TEST_API_KEY!,
    baseURL: 'https://api-test.example.com'
  })

  it('should create and retrieve user', async () => {
    // Create
    const created = await client.users.create({
      email: `test-${Date.now()}@example.com`
    })

    expect(created.id).toBeDefined()

    // Retrieve
    const retrieved = await client.users.retrieve(created.id)
    expect(retrieved.email).toBe(created.email)

    // Cleanup
    await client.users.delete(created.id)
  })
})

SDK Versioning and Deprecation

Guide to semantic versioning, deprecation strategies, and API version pinning.

Semantic Versioning (SemVer)

Follow MAJOR.MINOR.PATCH:

• MAJOR: Breaking changes (2.0.0)
• MINOR: New features, backward compatible (1.1.0)
• PATCH: Bug fixes (1.0.1)

Examples

1.0.0 → 1.0.1  Bug fix (safe to update)
1.0.0 → 1.1.0  New feature (safe to update)
1.0.0 → 2.0.0  Breaking change (review before updating)

Deprecation Pattern

TypeScript Decorator

function deprecated(message: string, since: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value

    descriptor.value = function (...args: any[]) {
      console.warn(
        `[DEPRECATED] ${propertyKey} is deprecated since ${since}.\n${message}`
      )
      return originalMethod.apply(this, args)
    }

    return descriptor
  }
}

class UsersResource {
  @deprecated('Use users.list() instead', 'v2.0.0')
  async getAll() {
    return this.list()
  }

  async list() {
    // New method
  }
}

Python Decorator

import warnings
from functools import wraps

def deprecated(message: str, since: str):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            warnings.warn(
                f"{func.__name__} is deprecated since {since}. {message}",
                DeprecationWarning,
                stacklevel=2
            )
            return func(*args, **kwargs)
        return wrapper
    return decorator

class UsersResource:
    @deprecated("Use users.list() instead", "v2.0.0")
    def get_all(self):
        return self.list()

API Version Pinning

const client = new APIClient({
  apiKey: 'sk_test_...',
  apiVersion: '2025-01-01'
})

// SDK sends version in header
headers: {
  'API-Version': '2025-01-01'
}