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