Comprehensive API Integration Specialist

A Claude Code skill for integrating external APIs into your applications with production-ready patterns. Covers authentication, error handling, rate limiting, retry logic, response caching, webhook handling, and SDK creation — focused on building reliable, maintainable API integrations.

When to Use This Skill

Choose API Integration Specialist when:

• You need to integrate a third-party API (Stripe, Twilio, SendGrid, etc.)
• You want production-ready error handling and retry logic for API calls
• You need to handle webhooks from external services
• You want to build a client SDK wrapper around an API
• You need to manage API authentication, rate limiting, and caching

Consider alternatives when:

• You're building your own API (use an API documentation generator skill)
• You need database integration (use a database skill)
• You want to design an API from scratch (use an API design skill)

Quick Start

Copy
# Install the skill
claude install comprehensive-api-integration-specialist

# Integrate a third-party API
claude "Integrate the Stripe API for subscription billing: create customer, subscribe, handle invoices, and process webhooks"

# Add retry and error handling
claude "Add production-ready error handling to my OpenAI API integration: retries, rate limit handling, and fallback logic"

# Build an API client
claude "Build a typed API client for this REST API: [paste OpenAPI spec or endpoint list]"

Core Concepts

Integration Architecture

Application Layer
├── API Client (typed, handles auth)
│   ├── Request Builder (URL, headers, body)
│   ├── Response Parser (validation, typing)
│   ├── Error Handler (classification, mapping)
│   └── Auth Manager (tokens, refresh, rotation)
├── Middleware
│   ├── Retry Logic (exponential backoff)
│   ├── Rate Limiter (token bucket, sliding window)
│   ├── Cache Layer (response caching, invalidation)
│   └── Logger (request/response logging)
└── Webhook Handler
    ├── Signature Verification
    ├── Idempotency (deduplicate events)
    ├── Event Router (type → handler mapping)
    └── Dead Letter Queue (failed processing)

Error Handling Strategy

HTTP Status	Classification	Action
400	Client error (bad request)	Don't retry, fix the request
401	Authentication failed	Refresh token, then retry once
403	Authorization failed	Don't retry, check permissions
404	Resource not found	Don't retry, handle gracefully
429	Rate limited	Retry after Retry-After header
500	Server error	Retry with exponential backoff
502/503	Service unavailable	Retry with exponential backoff
Timeout	Network timeout	Retry with increasing timeout

Retry Pattern

Copy
async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries: 3, baseDelay: 1000, maxDelay: 30000 }
): Promise<T> {
  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryable(error) || attempt === options.maxRetries) throw error;
      const delay = Math.min(
        options.baseDelay * Math.pow(2, attempt) + Math.random() * 1000,
        options.maxDelay
      );
      await sleep(delay);
    }
  }
}

Configuration

Parameter	Type	Default	Description
retry_attempts	number	3	Maximum retry attempts
retry_backoff	string	"exponential"	Backoff: exponential, linear, fixed
timeout_ms	number	30000	Request timeout in milliseconds
cache_ttl	number	300	Response cache TTL in seconds
rate_limit	number	100	Max requests per minute
log_level	string	"error"	Logging: debug, info, warn, error

Best Practices

1. Never trust external API responses — Validate every response against an expected schema using Zod or similar. APIs change without notice, and a missing field shouldn't crash your application. Fail gracefully with clear error messages.

2. Use exponential backoff with jitter — When retrying failed requests, wait longer between each attempt (1s, 2s, 4s) and add random jitter to prevent thundering herd problems. This is especially important when recovering from rate limiting.

3. Implement circuit breakers — If an API fails repeatedly, stop calling it temporarily. After 5 consecutive failures, open the circuit for 60 seconds. This prevents cascading failures and reduces load on a struggling service.

4. Verify webhook signatures — Every webhook handler must verify the request signature using the service's shared secret. Without verification, anyone can send fake webhook events to your endpoint.

5. Store raw webhook payloads — Before processing a webhook event, store the raw payload in your database. This gives you a complete audit trail and the ability to replay events if processing fails.

Common Issues

Rate limited by external API — Implement a token bucket rate limiter on your side. Space requests to stay under the limit rather than hitting the limit and waiting. Use the Retry-After header when you do get rate limited.

API changes break integration — Pin your API version if the service supports it. Validate response schemas to catch breaking changes early. Monitor for deprecation notices and plan migrations proactively.

Webhook events processed multiple times — Implement idempotency using the event ID. Before processing, check if you've already handled that event ID. Store processed IDs with a TTL to prevent unbounded growth.