api-client

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

const 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:

const 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:

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

OAuth 2.0:

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

Step 3: Make Requests

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

// POST request
const newUser = await client.post('/users', {
  name: 'John Doe',
  email: '[e-mail]'
});

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

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

Step 4: Handle Errors

try {
  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

const 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

client.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:

Status Code	Category	Retry?	Action
400	Client Error	No	Fix request
401	Auth Error	No	Refresh token
403	Permission	No	Check permissions
404	Not Found	No	Check endpoint
429	Rate Limit	Yes	Wait and retry
500	Server Error	Yes	Retry
503	Unavailable	Yes	Retry

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

Validation

Validate API configuration before using:

python 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)