---

name: api-client description: REST API client builder with authentication, error handling, retry logic, and request management. Supports OAuth, JWT, API keys. Use when building API integrations, creating API clients, or working with REST services.

API Client Builder

Overview

Build robust REST API clients with authentication, comprehensive error handling, automatic retries, and request/response management.

Quick Start

Basic API Client

Copyconst client = new APIClient({
  baseURL: 'https://api.example.com',
  apiKey: process.env.API_KEY
});

const response = await client.get('/users');
console.log(response.data);

Features

• ✓ Multiple authentication methods (API key, OAuth, JWT)
• ✓ Automatic retry with exponential backoff
• ✓ Request/response logging
• ✓ Error classification and handling
• ✓ Rate limiting support
• ✓ Request timeout configuration

Workflow

Step 1: Configure Client

Create client with base configuration:

Copyconst client = new APIClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  retries: 3
});

Step 2: Add Authentication

See references/authentication-guide.md for all methods.

API Key:

Copyclient.setAuth({
  type: 'apiKey',
  key: process.env.API_KEY
});

OAuth 2.0:

Copyclient.setAuth({
  type: 'oauth',
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET
});

Step 3: Make Requests

Copy// GET request
const users = await client.get('/users');

// POST request
const newUser = await client.post('/users', {
  name: 'John Doe',
  email: 'john@example.com'
});

// PUT request
const updated = await client.put('/users/123', {
  name: 'Jane Doe'
});

// DELETE request
await client.delete('/users/123');

Step 4: Handle Errors

Copytry {
  const response = await client.get('/users');
  console.log(response.data);
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Request failed:', error.message);
  }
}

Configuration

Complete Configuration Options

Copyconst client = new APIClient({
  // Base configuration
  baseURL: 'https://api.example.com',
  timeout: 5000,                  // Request timeout (ms)

  // Retry configuration
  retries: 3,                     // Number of retries
  retryDelay: 1000,               // Initial retry delay (ms)
  retryMult iplier: 2,              // Exponential backoff multiplier

  // Authentication (see references/authentication-guide.md)
  auth: {
    type: 'apiKey',
    key: process.env.API_KEY
  },

  // Headers
  headers: {
    'Content-Type': 'application/json',
    'Custom-Header': 'value'
  },

  // Logging
  logging: true,                  // Enable request/response logging
  logLevel: 'info'               // debug, info, warn, error
});

See templates/api-config-template.json for complete configuration template.

Authentication Methods

Method 1: API Key

Copyclient.setAuth({
  type: 'apiKey',
  key: process.env.API_KEY,
  header: 'X-API-Key'  // Optional, default: 'Authorization'
});

Method 2: OAuth 2.0

See references/authentication-guide.md#oauth for complete OAuth flow.

Method 3: JWT

See references/authentication-guide.md#jwt for JWT implementation.

Error Handling

Error Classification

Errors are classified into categories for appropriate handling:

See references/error-handling.md for complete error handling strategies.

Validation

Validate API configuration before using:

Copypython scripts/validate-config.py config.json

Templates

Copy templates from templates/ directory:

• api-config-template.json - Complete configuration
• error-handler-template.js - Error handling code
• retry-logic-template.js - Retry implementation

References

• Authentication Guide - All auth methods
• Error Handling - Comprehensive error strategies
• Rate Limiting - Handle rate limits
• Testing - Test API clients

---

Version: 1.0 Last Updated: October 25, 2025 Example Type: Complex skill (full structure)