API Client Generator

Overview

Generates production-ready API clients with type safety, error handling, and testing.

When to use:

• •User asks to integrate with an external API
• •Building SDK wrapper for a service
• •Creating typed HTTP client
• •Implementing service-to-service communication

Announce: "I'm using the api-client-generator skill to create a type-safe API client"

Process

Step 1: Analyze API Specification

Check for API documentation:

# Look for OpenAPI/Swagger spec
find . -name "*.yaml" -o -name "*.yml" | grep -E "(openapi|swagger)"

# Check for API docs
ls -la docs/api/ 2>/dev/null

If OpenAPI spec exists, use scripts/parse-openapi.sh to generate types.

Step 2: Generate Client Structure

Use the template generator:

scripts/generate-client.sh <service-name> <language>

This creates:

• •Client class with configuration
• •Request/response types
• •Error handling
• •Retry logic
• •Rate limiting

Step 3: Implement Methods

For each API endpoint:

1. •Define request/response types
2. •Add method to client class
3. •Include error handling
4. •Add retry logic if idempotent
5. •Write unit test

Example from template:

async getUser(id: string): Promise<User> {
  return this.request<User>({
    method: 'GET',
    path: `/users/${id}`,
    retryable: true,
    timeout: 5000
  });
}

Step 4: Add Integration Tests

Use templates/integration-test.tpl to create tests:

templates/apply-template.sh integration-test.tpl > tests/integration.test.ts

Step 5: Generate Documentation

scripts/generate-docs.sh > API_CLIENT.md

Validation

• • All endpoints have type-safe methods
• • Error responses are properly typed
• • Retry logic only on idempotent operations
• • Rate limiting is configurable
• • Authentication is properly handled
• • Tests achieve >80% coverage
• • Documentation includes all examples

Common Issues

Issue: Rate limit errors

• •Solution: Implement exponential backoff with jitter

Issue: Type mismatches

• •Solution: Regenerate from latest API spec

Issue: Network timeouts

• •Solution: Make timeout configurable per endpoint

Resources

• •scripts/parse-openapi.sh - Parse OpenAPI spec to TypeScript/Python types
• •scripts/generate-client.sh - Generate client boilerplate
• •scripts/generate-docs.sh - Create markdown documentation
• •templates/client-class.tpl - Base client class template
• •templates/integration-test.tpl - Integration test template
• •reference/best-practices.md - API client best practices