api-client-generator

name	api-client-generator
description	Use when creating REST API clients, SDK wrappers, or HTTP service integrations. Generates type-safe client code with retry logic, error handling, rate limiting, and comprehensive tests. Triggered by requests to integrate external APIs, build SDK clients, or create service wrappers.
maturity	stable
version	2.0.0

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